Stacked PRs

Use GitHub's gh stack extension. It already does parent tracking, cascading rebase, PR base retargeting, and bottom-up merging. Do not hand-roll this with git rebase --update-refs, git config branch.*.parent, or manual gh pr create --base — that reimplements the extension badly and drifts from what GitHub's UI shows.

Public preview — flags may change. gh stack <cmd> --help is authoritative over this file.

First: does this actually need to be a stack?

Stacking couples the PRs. They merge bottom-up only, so a review stall or a revert on a lower layer blocks everything above it.

Before running any command here, check whether the changes actually depend on each other — later layers building on earlier layers' code, or a split of one logical change too big to review at once. If they're independent (unrelated files, either could merge first, no shared new symbols), stop and ask the user whether they really want a stack, and say why you're asking: independent PRs opened straight against the trunk merge in any order and don't block each other. Only proceed once they confirm.

Setup (once)

gh extension install github/gh-stack
gh stack alias        # optional: shorter command

If the repo's trunk is not the default branch, every init must say so, or the bottom PR targets the wrong branch:

gh stack init --base develop <bottom-branch>

Create a stack

gh stack init feat-auth          # add --base <trunk> if trunk isn't the default branch
gh stack add -Am "api routes"    # -A stages all, -m commits, then branches
gh stack add -Am "ui"
gh stack submit                  # push + create/update PRs, interactive editor

gh stack submit opens an editor for titles/bodies; --auto skips it and generates titles from commits, --open marks PRs ready for review (without it, --auto creates drafts). Commit messages become the PR titles, so write them the way you want the PR titled.

Already have branches? Adopt them bottom-to-top instead of recreating:

gh stack init feat/auth feat/api feat/ui

Already have open PRs you don't want tracked locally? gh stack link --base <trunk>.

Adapt to your repo

gh stack submit creates the PRs, which means any repo-specific PR skill or convention you normally rely on is bypassed. Retrofit those rules after submit rather than before:

• Apply required labels per PR: gh pr edit <n> --add-label <label>.
• Run any mandatory post-PR step once for the whole stack, not once per layer.
• Verify the bottom PR targets the intended trunk: gh stack view.
• If your repo enforces a title format (ticket prefixes and the like), put it in the commit message — that is what becomes the PR title.

Day to day

gh stack view            # -s for short, --json for scripting
gh stack sync            # fetch, rebase, push, sync PR state — the one you want most days
gh stack rebase          # cascading rebase only; --downstack / --upstack to limit scope
gh stack push            # push branches without touching PRs
gh stack modify          # interactively reorder/restructure; --continue / --abort
gh stack up | down | top | bottom | trunk | switch | checkout

Reach for gh stack sync before assuming a stack is broken — most "my diff looks wrong" reports are just a stale local stack after trunk moved.

Merge

gh stack merge --squash      # bottom-up; can merge several layers at once

GitHub retargets the remaining PRs onto the trunk automatically as lower layers merge. Never merge a middle PR first, and never merge a stacked PR from the web UI's plain merge button unless you've confirmed everything below it is already in.

Bail out

gh stack unstack --local     # drop local tracking, leave the PRs alone
gh stack unstack             # also unstack them on GitHub