Stacked Pull Requests in GitHub
How engineering teams break large changes into a chain of small, dependent pull requests — keeping reviews fast and focused while a bigger feature quietly takes shape underneath.
Picture a construction crew building a house floor by floor. They don’t wait for the entire building to be finished before an inspector checks anything — the foundation gets inspected first, then the ground floor gets built and inspected while the foundation is already approved, then the next floor goes up on top of that. Stacked pull requests bring exactly this idea to code review: instead of one enormous change waiting weeks for a single exhausting review, a big feature is split into a sequence of small pull requests, each one built directly on top of the last, each reviewed on its own, and each mergeable the moment it’s approved — without waiting for the whole stack to be finished first.
1Core Concepts: What Is a Stacked Pull Request?
In an ordinary GitHub workflow, a developer branches off main, makes changes, and opens a single pull request back into main. A stacked pull request workflow instead creates a sequence of branches, where branch two is created from branch one (not from main), branch three is created from branch two, and so on. Each branch gets its own pull request, and each pull request’s base is the branch beneath it in the stack, not main directly — except for the very first one at the bottom.
Think of a stacked pull request chain like a set of nested Russian dolls, but built upward instead of downward. The smallest doll (the first PR) has to be closed and sealed before the next slightly bigger doll can be placed around it. Each doll is reviewed and finished on its own terms, but the final assembled figure only exists once every layer, from the inside out, is complete.
A Simple Three-PR Stack, Conceptually
PR #1 — base: main
Introduces a new data model. Small, self-contained, easy to review in isolation.
PR #2 — base: PR #1’s branch
Adds an API endpoint that uses the new data model. Reviewers only see the new endpoint code, not the model again.
PR #3 — base: PR #2’s branch
Adds the user interface that calls the new endpoint. Again, reviewers see only the new, relevant diff.
What makes a set of pull requests “stacked” rather than just “a lot of branches” is the explicit base-branch chaining: each PR’s diff shows only what changed relative to the PR directly below it, not the full accumulated change since main.
2Why This Exists: The Problem It Solves
Large pull requests are one of the most consistently cited sources of friction in software teams. A 2,000-line pull request sits in review for days because reviewers keep postponing something that big, or skim it superficially because a truly careful read would take hours. Meanwhile, the author is blocked from building the next piece of work cleanly, because it depends on code that hasn’t merged yet, so it either sits on their own machine unshared, or gets crammed into the same giant, unreviewable pull request, making the problem worse.
Stacked pull requests exist to break this cycle without forcing developers to simply wait until an entire feature is finished before sharing any of it. By splitting work into a chain of small, individually reviewable pieces, each PR can be understood, discussed, and approved in minutes rather than hours, reviewers see focused, coherent diffs instead of an undifferentiated wall of changes, and the author can keep building the next layer immediately, in the open, instead of hiding unreviewed work in one local branch.
PER REVIEW
DEVELOPMENT
FIRST MERGE
3Architecture & Components
1. The Trunk (main)
The stable branch everything ultimately merges into. Only the bottom-most pull request in a stack has main as its base.
2. A Chain of Feature Branches
Each branch in the stack is created directly from the branch above it, not from main. This means each branch’s history literally contains all the commits from every layer beneath it, plus its own new commits.
3. A Chain of Pull Requests with Non-Main Bases
GitHub allows a pull request’s base to be set to any branch in the repository, not just main. A stacked PR workflow relies entirely on this: PR #2’s base is set to Branch A (not main), so its diff only shows what’s new in Branch B relative to Branch A.
4. Independent Review Threads
Because each PR has its own diff, its own comment thread, and its own approval state, reviewers can focus entirely on one layer without needing to re-review everything beneath it each time.
5. A Rebase-and-Retarget Mechanism
When the bottom PR merges into main, every branch above it must be rebased and every PR above it must have its base retargeted — either manually, or automatically by a stacking tool (see Chapter 9).
“How does GitHub know PR #2 shouldn’t show PR #1’s changes too?” A strong answer: it doesn’t “know” anything special — it simply computes the diff between the PR’s base branch and its head branch, and because the base was deliberately set to Branch A instead of main, PR #1’s commits are already “inside” that base and therefore excluded from the diff.
4Internal Working: How the Diff Stays Small
The mechanism that makes stacking work is the same one Git always uses to compute a pull request’s diff: a three-way comparison between the base branch, the head branch, and their common ancestor commit. When a PR’s base is main, that comparison naturally includes everything since main last diverged. When a PR’s base is instead another feature branch, the comparison starts from that branch’s latest commit, so only commits added after that point show up as “new” in the pull request.
It’s like proofreading a book chapter by chapter. If someone hands you the entire manuscript every time, you re-read chapters you already approved looking for new mistakes. If instead they hand you only the newly written chapter, referencing “continues directly after the chapter you already signed off on,” your proofreading stays focused and fast — and that’s exactly what setting a PR’s base to the previous branch accomplishes.
Why Merging the Bottom PR Requires Updating Everything Above
Once PR #1 merges into main, Branch A’s commits now live directly on main. Branch B, however, was built from the old Branch A, which now has a different (merged) identity on main. Left alone, PR #2 would still show its base as the old, now-redundant Branch A, causing confusing or duplicated diffs. The stack must be updated: Branch B gets rebased onto the new main, and PR #2’s base gets retargeted from Branch A to main. This cascades up through every remaining layer of the stack.
This rebase-and-retarget cascade is the single biggest source of friction in stacked pull requests, and it is the exact problem dedicated stacking tools were built to automate, because doing it by hand across a five- or six-deep stack, repeatedly, is tedious and error-prone.
5Data Flow & Lifecycle of a Stack
| Stage | What Happens | Who’s Involved |
|---|---|---|
| Planning the split | A large feature is mentally divided into small, logically ordered layers before any branch is created. | Author |
| Branch A created from main | First layer of work is committed to a new branch off the trunk. | Author |
| PR #1 opened, base: main | First pull request is opened and sent for review. | Author, Reviewer 1 |
| Branch B created from Branch A | Before PR #1 even merges, the next layer of work begins on top of it. | Author |
| PR #2 opened, base: Branch A | Second pull request opened, showing only Branch B’s new commits. | Author, Reviewer 2 |
| PR #1 approved and merged | Branch A’s changes land on main. | Reviewer 1, Author |
| Stack updates cascade | Branch B is rebased onto main; PR #2’s base is retargeted to main. | Author (or stacking tool) |
| Process repeats up the stack | Each subsequent PR merges, and every branch above it rebases and retargets in turn. | Author, remaining reviewers |
| Stack fully merged | Every layer has landed on main in order; the full feature is now live in trunk history. | Whole team |
Merge Order Matters
Because each layer depends on the one below it, a stack must merge from the bottom up, in order. Merging a higher PR before the ones beneath it would pull in commits that haven’t been approved yet, breaking the entire point of isolated review.
6Advantages, Disadvantages & Trade-offs
Advantages
- Each pull request stays small and genuinely reviewable, improving review depth and speed.
- Authors can keep building the next layer immediately, instead of blocking on a single giant review.
- Feedback surfaces earlier, on smaller pieces, before a whole feature is fully built.
- Git history ends up cleanly organized into logical, incremental commits rather than one sprawling change.
- Multiple reviewers can review different layers in parallel if a team distributes the work.
Disadvantages & Costs
- Rebasing and retargeting bases by hand across a deep stack is tedious and error-prone without tooling.
- A change requested on a lower PR forces every branch above it to rebase again, which can feel disruptive.
- GitHub’s native UI has limited built-in awareness of “stacks” as a concept, so context can feel scattered across separate PR pages.
- New contributors often find the workflow conceptually confusing at first, compared to a single feature branch.
- Merge order discipline is required; merging out of order can silently reintroduce unreviewed code.
The Central Trade-off
Stacked pull requests trade extra branch-management overhead for dramatically smaller, faster, higher-quality reviews. For a quick one-file bug fix, the overhead isn’t worth it. For a substantial feature that would otherwise become one unreviewable mega-PR, the trade-off usually favors stacking, especially once a team adopts tooling that automates the rebase-and-retarget cascade.
7Security
Stacked pull requests are primarily a workflow and productivity pattern rather than a security control, but they carry real security-relevant consequences for how review actually functions.
Higher Review Fidelity
Smaller diffs make it far more likely a reviewer actually reads and understands every line, rather than skimming a huge change and rubber-stamping it.
Clear Attribution Per Layer
Each logical unit of work has its own clean approval trail, making it easier to trace exactly who approved what, and when.
Merging Out of Order
If a higher-layer PR is accidentally merged before a lower one, unreviewed or unapproved commits can land on the trunk branch.
Stale Base Confusion
If a base isn’t retargeted correctly after a lower PR merges, a reviewer might approve a diff that actually still contains old, already-merged changes mixed in with new ones, obscuring what’s truly new.
Teams that use stacked pull requests still benefit from standard branch protection on main — required reviews and required status checks apply at each merge step exactly as they would for any other pull request, so the discipline stacking encourages and the guarantees branch protection enforces reinforce each other rather than conflicting.
8Monitoring, Logging & Metrics
Time-to-First-Review Per Layer
Tracking how quickly each individual PR in a stack gets its first review shows whether the smaller-diff approach is actually accelerating feedback as intended.
Average Chain Length
Very deep stacks (many layers) can signal a feature that could have been better scoped, or simply a team confidently using the pattern — worth watching over time either way.
Out-of-Sequence Merge Events
If tooling or CI can detect a higher-layer PR merging before a lower one, flagging it early avoids unreviewed code slipping onto the trunk branch.
Churn From Cascading Updates
A high rate of forced rebases across a stack can indicate the bottom layers are still changing too much to be a stable foundation for layers above them.
9Design Patterns & Anti-Patterns
Pattern
Use a dedicated stacking-aware tool or CLI extension to manage the branches and bases, rather than doing every rebase and retarget manually.
Why It Works
These tools track the stack as a single logical unit, automatically rebasing and retargeting every layer above a merged PR, which removes almost all the manual overhead that otherwise makes stacking painful at scale.
Pattern
Keep each layer’s PR description explicit about its position in the stack, linking to the PR immediately above and below it.
Why It Works
Because GitHub’s native UI doesn’t visually group a stack together, explicit cross-links are what let a reviewer or a new team member understand the full shape of the feature at a glance.
Pattern
Building a very deep stack (many layers) for a feature that could reasonably have been scoped smaller or merged in fewer steps.
Why It Fails
Excessive depth multiplies the rebase-and-retarget overhead every time a lower layer changes, and can make the overall feature harder to reason about than a well-scoped two- or three-layer stack would have been.
Pattern
Merging pull requests out of stack order because a higher layer happened to get approved first.
Why It Fails
It can pull unreviewed, unapproved commits from lower layers onto the trunk branch as a side effect, silently undermining the review guarantees the whole workflow exists to provide.
10Best Practices & Common Mistakes
Plan the Layers Before Coding
Sketch the intended sequence of small, logically ordered changes before starting, rather than discovering the split mid-implementation.
Keep Each Layer Independently Meaningful
Every PR in the stack should represent a coherent, understandable step on its own, not an arbitrary chunk of an otherwise inseparable change.
Merge Promptly, Bottom-Up
Letting an approved bottom-layer PR sit unmerged only delays every layer above it and increases the odds of painful rebase conflicts.
Communicate Stack Changes to Reviewers
If a lower layer changes after a higher layer was already reviewed, tell reviewers explicitly rather than letting a silent rebase confuse their mental model.
Common Mistakes
Forgetting to Retarget a Base After a Merge
A PR keeps pointing at a now-merged, deleted branch, producing a broken or misleading diff.
Building Too Many Layers Deep
A stack grows to six or seven PRs for a feature that would have been clearer as two or three, multiplying coordination overhead.
Merging Out of Sequence
A higher layer merges before a lower one is approved, pulling in unreviewed commits.
Not Rebasing Promptly After Lower-Layer Changes
Higher layers drift out of sync with an updated lower layer, causing confusing merge conflicts later.
No Visual Map of the Stack for Reviewers
Reviewers land on an isolated PR page with no context about where it sits in the larger chain, slowing review down rather than speeding it up.
11Real-World & Industry Examples
Large-Scale Engineering Organizations
Companies operating monorepos with very high commit volume and strict review culture commonly rely on stacked-diff workflows internally, treating small, incremental, individually-reviewed changes as a core engineering norm rather than an occasional technique.
Open Source Projects With High Review Bar
Projects that demand thorough review before any change lands often see contributors naturally split large features into a sequence of smaller, dependent pull requests, even without dedicated tooling, simply because maintainers are far more responsive to small, focused diffs.
Teams Adopting Dedicated Stacking Tools
A growing category of developer tools exists specifically to automate the branch and base management behind stacked pull requests, letting engineers describe their work as a linear stack of commits and have the tool handle creating, syncing, and retargeting the underlying GitHub pull requests automatically.
Refactoring-Heavy Codebases
Large refactors that touch many files are a natural fit for stacking: an initial PR introduces a new pattern in isolation, and subsequent PRs migrate one module at a time on top of it, each easy to review against a stable, already-approved foundation.
12Frequently Asked Questions
13Summary & Key Takeaways
Key Takeaways
- Stacked pull requests split one large feature into a chain of small, dependent pull requests, each built directly on the branch beneath it.
- The core mechanism is entirely ordinary GitHub functionality: each PR’s base is set to the previous layer’s branch instead of
main, so its diff shows only what’s new. - The main benefit is review quality and speed — small, focused diffs get read carefully and approved quickly, unlike sprawling mega-PRs.
- The main cost is the rebase-and-retarget cascade that must happen every time a lower layer merges, which dedicated stacking tools largely automate.
- Stacks must merge bottom-up, in order; merging out of sequence risks pulling unreviewed commits onto the trunk branch.
- It pairs naturally with existing branch protection rules, since each merge in the chain still passes through the same required reviews and checks.
- The pattern is most valuable for substantial features that would otherwise become one unreviewable pull request, and scales from solo contributors to large engineering organizations alike.