gh-stack
Manage GitHub stacked pull requests with the official gh stack extension (github/gh-stack). Use for stack creation, viewing, edits, push, submit, sync, rebase, merge, or checkout; when asked to split or isolate work for review; whenever the user mentions a stack, branch layers, dependent PRs, "stacked PR", "PR stack", or "gh stack"; or when a stack is checked out.
iuhoay · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add iuhoay/skills --skill gh-stackAbout this skill
name: gh-stack description: > Manage GitHub stacked pull requests with the official gh stack extension (github/gh-stack). Use for stack creation, viewing, edits, push, submit, sync, rebase, merge, or checkout; when asked to split or isolate work for review; whenever the user mentions a stack, branch layers, dependent PRs, "stacked PR", "PR stack", or "gh stack"; or when a stack is checked out. allowed-tools:
- Bash
- Read
- Grep
GitHub Stacked PRs
gh stack is a GitHub CLI extension for stacked branches and pull
requests. A stack is an ordered chain of branches rooted on a trunk, where each branch has one PR
based on the branch below it, so a reviewer sees only that layer's diff.
gh stack prints a stack trunk-first, left to right:
(main) <- auth <- api <- frontend
Left is the bottom, right is the top. auth is based on main and merges first;
frontend merges last. up moves toward the top, away from trunk; down moves toward it.
Foundational work belongs at the bottom, code that depends on it above. For how to choose the
layers, read references/stack-design.md.
Setup
Check the extension before first use in a session (/gh-stack:setup walks through this):
gh extension list | grep stack || gh extension install github/gh-stack
git config rerere.enabled true # remember conflict resolutions
git config remote.pushDefault origin # required if the repo has more than one remote
Optional: gh stack alias installs a gs-style shortcut for gh stack.
Non-interactive use
gh stack branches on whether stdout is a TTY. Piped, most commands error cleanly or print
static text; under a PTY the same commands open a prompt or a full-screen TUI and block forever.
Agent harnesses differ, so always pass the flags below instead of relying on that detection.
Multiple remotes: never run push, submit, sync, rebase, or link without
--remote <name> unless remote.pushDefault is configured. checkout and trunk have no
--remote flag and require the config.
| Always run | Never run bare | Why |
|---|---|---|
gh stack view --json | gh stack view | opens a TUI under a PTY |
gh stack submit --auto | gh stack submit | prompts for a title per new PR |
gh stack merge <target> --yes | gh pr merge | gh pr merge cannot merge a stack |
gh stack init <branch>... | gh stack init | prompts for branch names |
gh stack add <branch> | gh stack add | prompts for a name, and fails even when piped |
gh stack checkout <target> | gh stack checkout | opens a selection menu |
gh stack up / down / top / bottom | gh stack switch | switch is menu-only |
| — | gh stack modify | TUI-only, no non-interactive path |
view --shortis safe in both modes, but it is formatted for humans. Use--jsonto parse.checkout <pr>when a different local stack already covers those branches cannot be forced. Rungh stack unstack --localfirst (this keeps the stack on GitHub), then retry.
Branch placement
- Starting multi-part work: create the stack before writing files. Do not implement every concern on trunk and split it later. Put one dependent concern in each layer, bottom to top.
- Editing an existing stack: check out the layer that owns the change before editing. Never
commit a lower layer's concern on the current top branch. Run
gh stack view --json; if ownership is unclear, inspectgit log --all -- <path>. Then check out the owner, edit, commit, rebase upstack, and return to top.
gh stack down # or: gh stack checkout api
git add ... && git commit -m "Add get-user endpoint"
gh stack rebase --upstack # replay every branch above onto the change
gh stack top # return to where you were
gh stack push
Core loop
gh stack init auth # create the stack and check out its branch
git add ... && git commit -m "Add auth middleware"
gh stack add api # next layer, branched from the current one
git add ... && git commit -m "Add API routes"
gh stack submit --auto # push every branch and open draft PRs
gh stack view --json # confirm
Add --open to submit to create PRs ready for review instead of drafts. Branch names are
verbatim — gh stack add refactor/foo creates refactor/foo. Existing branches passed to init
are adopted automatically (the legacy --adopt flag is deprecated).
Staying in sync
gh stack sync # fetch, reconcile with GitHub, rebase, push, refresh PR state
gh stack sync --prune # also delete local branches for merged PRs
Pruning never happens without --prune when non-interactive. sync never opens PRs — run
submit for that. If the local and remote stacks have diverged, sync prints both chains, makes
no changes, and exits 0 with Sync aborted — see references/troubleshooting.md.
Merging
Scope the merge with an argument:
gh stack merge 42 --yes # PR #42 plus every unmerged PR below it
gh stack merge 7 --yes # every unmerged PR in stack #7
gh stack merge 42 --yes --squash # or --merge, --rebase, --merge-method <method>
Pass a PR number to merge that PR and every unmerged PR below it, or a stack number to merge every unmerged PR in that stack. The operation is all-or-nothing: if any PR in that set cannot merge, none do.
Without a method flag the last-used method is reused. If the base branch uses a merge queue, the stack is queued instead and the queue picks the method, ignoring any flag you passed with a warning; queued PRs may land in separate groups.
Reading state
gh stack view --json writes JSON to stdout. Status messages go to stderr — do not parse
them, branch on exit codes instead.
trunk string
currentBranch string
branches[] name, head, base, isCurrent, isMe
Read the complete source ↗