gh-stack

1---2name: gh-stack3description: >4  Manages stacked PRs and splits multi-part work into reviewable branches with gh-stack.5  Use for stack creation, viewing, edits, push, submit, sync, rebase, merge, or checkout;6  when asked to split or isolate work for review; whenever a user mentions a stack,7  branch layers, dependent PRs, or gh stack; or when a stack is checked out.8metadata:9  author: github10  version: '0.1.0'11---12 13# gh-stack14 15`gh stack` is a [GitHub CLI](https://cli.github.com/) extension for stacked branches and pull16requests. A stack is an ordered chain of branches rooted on a trunk, where each branch has one PR17based on the branch below it, so a reviewer sees only that layer's diff.18 19`gh stack` prints a stack trunk-first, left to right:20 21```22(main) <- auth <- api <- frontend23```24 25Left is the **bottom**, right is the **top**. `auth` is based on `main` and merges first;26`frontend` merges last. `up` moves toward the top, away from trunk; `down` moves toward it.27Foundational work belongs at the bottom, code that depends on it above. For how to choose the28layers, read `references/stack-design.md`.29 30## Setup31 32```bash33gh extension install github/gh-stack34git config rerere.enabled true         # remember conflict resolutions35git config remote.pushDefault origin   # required if the repo has more than one remote36```37 38## Non-interactive use39 40`gh stack` branches on whether **stdout is a TTY**. Piped, most commands error cleanly or print41static text; under a PTY the same commands open a prompt or a full-screen TUI and block forever.42Agent harnesses differ, so always pass the flags below instead of relying on that detection.43 44**Multiple remotes:** never run `push`, `submit`, `sync`, `rebase`, or `link` without45`--remote <name>` unless `remote.pushDefault` is configured. `checkout` and `trunk` have no46`--remote` flag and require the config.47 48| Always run                                | Never run bare      | Why                                           |49| ----------------------------------------- | ------------------- | --------------------------------------------- |50| `gh stack view --json`                    | `gh stack view`     | opens a TUI under a PTY                       |51| `gh stack submit --auto`                  | `gh stack submit`   | prompts for a title per new PR                |52| `gh stack merge <target> --yes`           | `gh pr merge`       | `gh pr merge` cannot merge a stack            |53| `gh stack init <branch>...`               | `gh stack init`     | prompts for branch names                      |54| `gh stack add <branch>`                   | `gh stack add`      | prompts for a name, and fails even when piped |55| `gh stack checkout <target>`              | `gh stack checkout` | opens a selection menu                        |56| `gh stack up` / `down` / `top` / `bottom` | `gh stack switch`   | `switch` is menu-only                         |57| —                                         | `gh stack modify`   | TUI-only, no non-interactive path             |58 59- `view --short` is safe in both modes, but it is formatted for humans. Use `--json` to parse.60- **`checkout <pr>` when a different local stack already covers those branches** cannot be forced.61  Run `gh stack unstack --local` first (this keeps the stack on GitHub), then retry.62 63## Branch placement64 65- **Starting multi-part work:** create the stack before writing files. Do not implement every66  concern on trunk and split it later. Put one dependent concern in each layer, bottom to top.67- **Editing an existing stack:** check out the layer that owns the change before editing. Never68  commit a lower layer's concern on the current top branch. Run `gh stack view --json`; if69  ownership is unclear, inspect `git log --all -- <path>`. Then check out the owner, edit, commit,70  rebase upstack, and return to top.71 72```bash73gh stack down                   # or: gh stack checkout api74git add ... && git commit -m "Add get-user endpoint"75gh stack rebase --upstack       # replay every branch above onto the change76gh stack top                    # return to where you were77gh stack push78```79 80## Core loop81 82```bash83gh stack init auth              # create the stack and check out its branch84git add ... && git commit -m "Add auth middleware"85gh stack add api                # next layer, branched from the current one86git add ... && git commit -m "Add API routes"87gh stack submit --auto          # push every branch and open draft PRs88gh stack view --json            # confirm89```90 91Add `--open` to `submit` to create PRs ready for review instead of drafts. Branch names are92verbatim — `gh stack add refactor/foo` creates `refactor/foo`.93 94## Staying in sync95 96```bash97gh stack sync                   # fetch, reconcile with GitHub, rebase, push, refresh PR state98gh stack sync --prune           # also delete local branches for merged PRs99```100 101Pruning never happens without `--prune` when non-interactive. If the local and remote stacks have102diverged, `sync` prints both chains, makes no changes, and exits 0 with `Sync aborted` — see103`references/troubleshooting.md`.104 105## Merging106 107Scope the merge with an argument:108 109```bash110gh stack merge 42 --yes          # PR #42 plus every unmerged PR below it111gh stack merge 7 --yes           # every unmerged PR in stack #7112gh stack merge 42 --yes --squash # or --merge, --rebase, --merge-method <method>113```114 115Pass a PR number to merge that PR and every unmerged PR below it, or a stack number to merge every116unmerged PR in that stack. The operation is all-or-nothing: if any PR in that set cannot merge,117none do.118 119Without a method flag the last-used method is reused. If the base branch uses a merge queue, the120stack is queued instead and the queue picks the method, ignoring any flag you passed with a121warning; queued PRs may land in separate groups.122 123## Reading state124 125`gh stack view --json` writes JSON to **stdout**. Status messages go to **stderr** — do not parse126them, branch on exit codes instead.127 128```129trunk           string130currentBranch   string131branches[]      name, head, base, isCurrent, isMerged, isQueued, needsRebase132branches[].pr   number, url, state ("OPEN" | "MERGED" | "QUEUED"); absent when no PR exists133```134 135`base` is the saved SHA of the parent branch that this branch was last known to contain. It may be136older than the parent's current tip. `needsRebase` is true when the current parent tip is no longer137an ancestor of the branch.138 139## Exit codes140 141| Code | Meaning                    | Recovery                                                   |142| ---- | -------------------------- | ---------------------------------------------------------- |143| 0    | Success                    | —                                                          |144| 1    | Generic error              | Read stderr                                                |145| 2    | Not in a stack             | `gh stack init`, or `gh stack checkout <target>`           |146| 3    | Rebase conflict            | Follow the Exit 3 recovery below                           |147| 4    | GitHub API failure         | Check `gh auth status`, retry                              |148| 5    | Invalid arguments          | Fix the invocation; see `<command> --help`                 |149| 6    | Disambiguation required    | Branch is in several stacks; check out a non-shared branch |150| 7    | Rebase already in progress | `gh stack rebase --continue` or `--abort`                  |151| 8    | Stack file locked          | Another `gh stack` process is writing; retry after ~5s     |152| 9    | Stacked PRs unavailable    | Not enabled on the repository; tell the user               |153| 10   | Modify recovery required   | `gh stack modify --abort`                                  |154 155**Exit 3 recovery:**156 157- After `gh stack rebase`: resolve the files, run `git add`, then158  `gh stack rebase --continue`; use `gh stack rebase --abort` to restore the stack.159- After `gh stack sync`: the stack has already been restored. Run `gh stack rebase` to recreate the160  conflict, then resolve and continue as above.161 162## Constraints163 164- Stacks are strictly linear: one parent, at most one child. Use separate stacks for parallel work.165- There is no non-interactive reorder or removal. Errors may suggest `gh stack modify`, but it is166  TUI-only — restructure with `unstack` then `init` instead.167- PR titles and bodies are auto-generated. Use `gh pr edit` afterwards to change them.168- `checkout <branch-name>` resolves against local stacks only. Use a stack or PR number to pull a169  stack down from GitHub.170 171## More detail172 173`gh stack <command> --help` is authoritative for flags and arguments. Note that174`gh stack help <command>` does **not** work — it prints the top-level help.175 176Open the reference whose trigger matches the task; no need to preload all three.177 178- `references/stack-design.md` — read before creating a stack, when deciding how many layers to179  use, what belongs in each one, or whether work belongs in a new stack.180- `references/commands.md` — read when a command fails unexpectedly or you need its preconditions,181  side effects, atomicity, or ordering guarantees.182- `references/troubleshooting.md` — read on a rebase conflict, after a squash-merge, on local and183  remote divergence, when restructuring a stack, or when driving stacks from another tool.184