Stacked (dependent) pull request workflow. Use when creating, managing, or troubleshooting stacked PRs, or when user mentions stacked diffs, dependent PRs, PR stacks, or breaking large features into smaller PRs.
Expert guidance for creating and managing stacked (dependent) pull requests.
git statusgit diff --stagedgit diffgit branch --show-currentgit log --oneline -10git log --oneline --graph --all -20Stacked PRs (also called dependent PRs or stacked diffs) is a workflow where you create multiple pull requests that build on top of each other. Each PR in the stack depends on the changes from the previous PR.
Traditional workflow:
main → feature-branch (large PR, 2000+ lines)
Stacked workflow:
main → feature-part-1 → feature-part-2 → feature-part-3
(small PR) (small PR) (small PR)
200 lines 200 lines 200 lines
✅ Good use cases:
❌ Avoid when:
See workflows/create-stacked-prs.md for step-by-step instructions on organizing unstaged changes into a reviewable stack.
Quick overview:
See workflows/update-stack-after-merge.md for instructions on rebasing and updating PR targets after merging base PRs.
Quick overview:
See workflows/recover-from-rebase.md for instructions on using reflog to recover from rebase errors.
Quick overview:
git reflogPlan before you start:
Example stack plan:
feat/auth/base - Core auth models and utilities
feat/auth/middleware - Auth middleware (depends on base)
feat/auth/endpoints - API endpoints (depends on middleware)
feat/auth/ui - Frontend UI (depends on endpoints)
Use consistent naming that shows hierarchy:
feat/<stack-name>/<component>
fix/<stack-name>/<component>
refactor/<stack-name>/<component>
Examples:
feat/auth/basefeat/auth/middlewarefeat/payments/stripe-integrationfeat/payments/payment-uiEach PR in the stack must:
Example test strategy:
PR 1 (base): Tests for models and utilities
PR 2 (middleware): Tests for middleware + integration tests
PR 3 (endpoints): Tests for endpoints + E2E tests
PR 4 (ui): UI tests + full E2E flow tests
Use clear PR descriptions that document dependencies:
## Summary
Adds JWT authentication middleware for protecting routes.
## Stack Information
- **Stack:** User Authentication
- **Position:** 2/4 (depends on #123, required by #125)
- **Base PR:** #123 (Core auth models)
- **Depends on:** #123
## Changes
- Authentication middleware
- Token validation logic
- Protected route decorators
## Testing
- Unit tests for middleware
- Integration tests with routes
- All tests pass
## Review Notes
This PR can be reviewed independently, but depends on #123 being merged first.
See templates/pr-description.md for a reusable template.
The git-stacked-prs skill includes scripts to automate common workflows:
Automatically rebase all branches in a stack with safety features:
${CLAUDE_PLUGIN_ROOT}/skills/git-stacked-prs/scripts/stack-rebase.sh main feat/auth-base feat/auth-middleware feat/auth-api
Features:
--force-with-lease for safety--dry-run for previewDisplay visual tree of stack structure with PR status:
${CLAUDE_PLUGIN_ROOT}/skills/git-stacked-prs/scripts/stack-status.sh --pr-status
Options:
--detail - Show commit summaries--pr-status - Include GitHub PR status (requires gh CLI)--json - JSON output for parsingBatch update PR base branches after merging a base PR:
${CLAUDE_PLUGIN_ROOT}/skills/git-stacked-prs/scripts/update-pr-targets.sh feat/auth-base main
Features:
gh CLI--no-rebase to only update targetsCreate backups before risky operations:
# Create backups
${CLAUDE_PLUGIN_ROOT}/skills/git-stacked-prs/scripts/stack-backup.sh create feat/auth-base feat/auth-middleware
# List backups
${CLAUDE_PLUGIN_ROOT}/skills/git-stacked-prs/scripts/stack-backup.sh list
# Restore from backup
${CLAUDE_PLUGIN_ROOT}/skills/git-stacked-prs/scripts/stack-backup.sh restore feat/auth-base
# Clean old backups
${CLAUDE_PLUGIN_ROOT}/skills/git-stacked-prs/scripts/stack-backup.sh clean --older-than 30
# Visual branch tree
git log --oneline --graph --all -20
# See what branches exist
git branch -a
# Compare branches
git log main..feat/auth/base --oneline
git log feat/auth/base..feat/auth/middleware --oneline
# Or use the automated script
${CLAUDE_PLUGIN_ROOT}/skills/git-stacked-prs/scripts/stack-status.sh
Use the automated script for safe, sequential rebasing:
${CLAUDE_PLUGIN_ROOT}/skills/git-stacked-prs/scripts/stack-rebase.sh main feat/auth/base feat/auth/middleware feat/auth/api
Or manually rebase each branch:
# Update base branch
git checkout feat/auth/base
git rebase main
git push --force-with-lease
# Update next branch
git checkout feat/auth/middleware
git rebase feat/auth/base
git push --force-with-lease
# Repeat for each branch
# During rebase, conflicts occur
git status # Identify conflicted files
# Edit files to resolve conflicts
# Remove conflict markers: <<<<<<<, =======, >>>>>>>
git add <resolved-files> # Stage resolved files
git rebase --continue # Continue rebase
# If things go wrong
git rebase --abort # Abort and start over
git reflog # Find previous HEAD to recover
After merging a base PR, update the next PR's target:
Symptoms: Commits appearing in wrong PRs, conflicts everywhere
Solution:
Solution: Use reflog to recover (see workflows/recover-from-rebase.md)
git reflog # Find lost commit
git cherry-pick <commit> # Apply lost commit
Solution: Resolve conflicts layer by layer, starting from base:
Symptom: PR includes commits from base branch that are already merged
Solution: Update PR target to point to main instead of the merged branch:
Add to ~/.gitconfig:
[alias]
stack-status = log --oneline --graph --all -20
stack-rebase = "!f() { git rebase $1 && git push --force-with-lease; }; f"
# View PR status
gh pr status
# View specific PR
gh pr view 123
# Check PR checks/tests
gh pr checks 123
@git-commits@git-advanced