Stacked PRs

Break large features into small, reviewable PRs that depend on each other. Merge in order for clean history.

Quick Reference

main ──────────────────────────────────────────● / PR #3 (final) ─────────────────────────●────┘ ← Merge last / PR #2 (middle) ────────────────────●──┘ ← Depends on #1 / PR #1 (base) ────────────────●── ← Merge first / feature/auth ──────●────●────● ← Development

Workflow

1. Plan the Stack

Identify logical chunks

Example: Auth feature

PR 1: Add User model + migrations

PR 2: Add auth service + tests

PR 3: Add login UI + integration tests

2. Create Base Branch

git checkout main git pull origin main git checkout -b feature/auth-base

Implement first chunk

git add -p git commit -m "feat(#100): Add User model" git commit -m "feat(#100): Add user migrations"

Push and create first PR

git push -u origin feature/auth-base gh pr create --base main --title "feat(#100): Add User model [1/3]"
--body "## Stack

• PR 1/3: User model (this PR)
• PR 2/3: Auth service (depends on this)
• PR 3/3: Login UI (depends on #2)

Changes

• Add User model with validation
• Add database migrations"

3. Stack Next PR

Branch from first PR's branch (not main!)

git checkout -b feature/auth-service

Implement second chunk

git add -p git commit -m "feat(#100): Add auth service" git commit -m "test(#100): Add auth service tests"

Push and create PR targeting FIRST branch

git push -u origin feature/auth-service gh pr create --base feature/auth-base
--title "feat(#100): Add auth service [2/3]"
--body "## Stack

• PR 1/3: User model (#101)
• PR 2/3: Auth service (this PR)
• PR 3/3: Login UI (depends on this)

Depends on #101 - merge that first"

4. Continue Stacking

git checkout -b feature/auth-ui

Implement third chunk

git commit -m "feat(#100): Add login form" git commit -m "test(#100): Add login integration tests"

git push -u origin feature/auth-ui gh pr create --base feature/auth-service
--title "feat(#100): Add login UI [3/3]"

Managing the Stack

When Base PR Gets Feedback

Make changes to base PR

git checkout feature/auth-base git add -p git commit -m "fix: Address review feedback" git push

Rebase dependent PRs

git checkout feature/auth-service git rebase feature/auth-base git push --force-with-lease

git checkout feature/auth-ui git rebase feature/auth-service git push --force-with-lease

When Base PR Merges

After PR #1 merges to main

git checkout main git pull origin main

Update PR #2 to target main now

gh pr edit 102 --base main

Rebase PR #2 on main

git checkout feature/auth-service git rebase main git push --force-with-lease

Repeat for PR #3 after #2 merges

Stack Visualization

Track your stack with comments:

PR Stack for Auth Feature (#100)

Merge order: #101 -> #102 -> #103

Automation Script

#!/bin/bash

stack-rebase.sh - Rebase entire stack after changes

STACK=( "feature/auth-base" "feature/auth-service" "feature/auth-ui" )

BASE="main"

for branch in "${STACK[@]}"; do echo "Rebasing $branch onto $BASE..." git checkout "$branch" git rebase "$BASE" git push --force-with-lease BASE="$branch" done

echo "Stack rebased successfully!"

Tools for Stacked PRs

GitHub CLI Extensions

Install stacked PR helper

gh extension install dlvhdr/gh-dash

View PR dependencies

gh pr view --json baseRefName,headRefName

Third-Party Tools

• Graphite - graphite.dev (full stack management)

• Stacked - stacked.dev

• git-branchless - github.com/arxanas/git-branchless

Best Practices

DO: ✅ Keep each PR < 400 lines ✅ Make each PR independently reviewable ✅ Document the stack in PR descriptions ✅ Number PRs clearly [1/3], [2/3], [3/3] ✅ Use draft PRs for incomplete stack items ✅ Rebase after feedback, don't merge

DON'T: ❌ Create circular dependencies ❌ Stack more than 4-5 PRs deep ❌ Leave stacks open for > 1 week ❌ Force push to already-approved PRs ❌ Merge out of order

When NOT to Stack

• Small features (< 300 lines total)

• Unrelated changes

• Urgent hotfixes

• Single-purpose refactors

PR Template for Stacked PRs

Summary

Brief description of this PR's changes

Stack Position

• PR 1/N: Description (#xxx) - [Status]
• PR 2/N: This PR
• PR 3/N: Description (#xxx) - [Status]

Dependencies

Depends on: #xxx (merge that first) Blocks: #xxx (must merge this first)

Changes

• Change 1
• Change 2

Test Plan

• Tests added
• CI passes

Related Skills

• git-workflow: Branching, commits, and recovery patterns

• create-pr: PR creation basics

References

• Stack Management

• Rebase Strategy