CodeCrab crab mascot logoCodeCrabYour AI Pull Request ReviewerDownload
Track lessons
GitGitHubCode reviewIntermediate5 min

Stacked PRs: Build and Review Dependent Branches

Large AI-generated pull requests are difficult to understand and risky to merge. A stacked PR keeps each layer small while preserving dependencies between schema, API and interface changes.

When to use

  • A feature naturally splits into dependent layers that reviewers can approve separately.
  • You want feedback on the foundation while the next layer is still being built.
  • An agent produced one large change that can be reorganized into reviewable branches.

Example

A password-reset feature becomes three branches: feat/1-schema, feat/2-api based on schema, and feat/3-ui based on API. Each PR shows only one layer.

TL;DR

Branch each part from the previous one, open each PR against its parent, and rebase the whole stack in one command.

bash
git rebase -i --autosquash --update-refs main

Steps

  1. 1

    Create the stack

    Start the first branch from main, then create each next branch from the preceding layer after committing its focused change.

    bash
    git switch -c feat/1-schema main
# commit
git switch -c feat/2-api
# commit
git switch -c feat/3-ui
# commit
  2. 2

    Open each PR against its parent

    Reviewers see only the diff of that layer.

    bash
    gh pr create --base main --head feat/1-schema
gh pr create --base feat/1-schema --head feat/2-api
gh pr create --base feat/2-api --head feat/3-ui
  3. 3

    Fix a lower layer and update everything above

    Work from the top branch: commit a fixup for the lower commit, then rebase once. --update-refs moves every branch in the stack (Git 2.38+).

    bash
    git switch feat/3-ui
git commit --fixup=<sha-in-feat/1-schema>
git rebase -i --autosquash --update-refs main
git push --force-with-lease origin feat/1-schema feat/2-api feat/3-ui
  4. 4

    After the bottom PR merges

    Move the rest of the stack onto main and retarget the next PR.

    bash
    git fetch origin
git switch feat/3-ui
git rebase --update-refs --onto origin/main feat/1-schema
gh pr edit feat/2-api --base main
  5. 5

    Make it the default

    Enable updateRefs globally if stacked branches are a regular workflow; future rebases will move the related local branch refs automatically.

    bash
    git config --global rebase.updateRefs true

Gotchas

  • Use --force-with-lease, never plain --force, when pushing rebased layers.
  • Squash-merging the bottom PR changes its commits; always rebase with --onto afterwards.
  • Keep each layer reviewable on its own: build passes and tests pass.
  • Three to five layers is the practical limit before reviews stall.

Cheat sheet

git rebase --update-refs <base>Rebase and move all stacked branches
git rebase --onto <new> <old>Move a stack to a new base
gh pr create --base <parent>PR against the layer below
gh pr edit <branch> --base mainRetarget after a merge
git push --force-with-leaseSafe push after rebase

Related

Sources

Reviewing agent output? CodeCrab reviews pull requests locally with your own AI tools.

PreviousNext