Stacked PRs

What Are Stacked PRs?

Stacked PRs (also called stacked pull requests, stacked diffs, or stacked branches) are a development workflow where a large feature or change is broken into a sequence of small, dependent pull requests. Each PR in the stack builds directly on top of the one before it, forming a chain that can be reviewed and merged incrementally from bottom to top.

Instead of submitting a single 2,000-line pull request that touches multiple layers of the application, a developer creates a series of focused PRs. For example, a new API endpoint might be split into: (1) database migration and model changes, (2) service layer logic, (3) API controller and validation, and (4) frontend integration. Each of these becomes its own PR, and each one targets the branch of the previous PR rather than the main branch.

The concept originates from diff-based workflows used at companies like Meta (formerly Facebook) and Google, where tools like Phabricator and Gerrit natively support reviewing individual commits or diffs in a stack. In the GitHub ecosystem, tools like Graphite, ghstack, and git-town have emerged to bring this workflow to pull request-based development.

How It Works

In a stacked PR workflow, each branch is created off the previous branch in the stack rather than off main. Here is a simplified example:

# Start from main
git checkout main && git pull

# PR 1: Database layer
git checkout -b stack/01-db-migration
# ... make changes, commit, push
# Open PR targeting main

# PR 2: Service layer (depends on PR 1)
git checkout -b stack/02-service-layer
# ... make changes, commit, push
# Open PR targeting stack/01-db-migration

# PR 3: API controller (depends on PR 2)
git checkout -b stack/03-api-controller
# ... make changes, commit, push
# Open PR targeting stack/02-service-layer

When PR 1 is approved and merged into main, PR 2 is rebased so that it now targets main, and the process continues up the chain. Tools like Graphite automate the rebasing, retargeting, and dependency tracking that would otherwise make this workflow tedious to manage manually.

The key constraint is ordering: PRs must be reviewed and merged from the bottom of the stack upward. A PR higher in the stack cannot be merged before the ones it depends on.

Why It Matters

Large pull requests are one of the most well-documented bottlenecks in software development. Research from Google and studies by SmartBear show that review quality drops sharply once a PR exceeds 400 lines of changes. Reviewers spend less time per line, miss more defects, and are more likely to rubber-stamp the approval.

Stacked PRs solve this by keeping each individual review small and focused. A reviewer looking at only the database migration layer can concentrate entirely on schema design, indexing, and data integrity without being distracted by unrelated controller logic. This means faster review turnaround, higher review quality, and fewer rounds of feedback.

For the developer, stacked PRs enable continuous forward progress. Instead of waiting for a single monolithic PR to be approved, they can push ahead on the next layer while earlier PRs are under review. This reduces idle time and keeps the developer in flow.

Teams that adopt stacked PRs commonly report 30-50% reductions in review cycle time, because reviewers can approve small, self-contained changes quickly rather than scheduling dedicated time for large reviews.

Best Practices

1. Keep each PR in the stack to a single concern. Each PR should represent one logical layer or one coherent change. Mixing concerns defeats the purpose of splitting the work.

2. Write clear PR descriptions that explain position in the stack. Label each PR with its position (e.g., “[2/4] Add service layer for user onboarding”) and link to the other PRs in the stack so reviewers understand the full picture.

3. Use tooling to manage the stack. Manually rebasing and retargeting branches is error-prone. Tools like Graphite, git-town, or ghstack handle the mechanical work of keeping the stack synchronized after merges and rebases.

4. Keep stacks short — ideally 3 to 5 PRs. Very deep stacks (8+ PRs) become difficult to manage and review. If a feature requires that many layers, consider whether it can be split into independent work streams instead.

5. Merge from the bottom up and rebase frequently. Always merge the lowest unmerged PR first. Rebase the rest of the stack regularly to minimize merge conflicts and keep diffs clean for reviewers.

Common Mistakes

1. Skipping tooling and managing stacks manually. Without automation, developers forget to retarget PRs after merges, introduce rebase conflicts, or accidentally merge out of order. This turns a productivity workflow into a source of frustration.

2. Creating stacks where PRs are not truly dependent. If two PRs touch unrelated files and have no logical dependency, they should be independent PRs rather than a stack. Stacking independent changes forces unnecessary sequential review and slows everything down.

3. Submitting stacks with no context linking the PRs together. Reviewers who see PR 3 of 5 with no explanation of the overall feature or links to the other PRs will struggle to understand the purpose of the change. Every PR in a stack should reference the full plan.