Use when working in a checked-out PR stack, handling dependent PRs or branch layers, or planning to split work into stacked PRs.

gh stack gh stack is a [GitHub CLI](https://cli.github.com/) 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: 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 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 stack merge scopes an explicitly requested whole stack merge 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 (none) gh stack modify TUI only, no non interactive path view short is safe in both modes, but it is formatted for humans. Use json to parse. checkout <pr when a different local stack already covers those branches cannot be forced. Run gh stack unstack local first (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, inspect git log all <path . Then check out the owner, edit, commit, rebase upstack, and return to top. Core loop 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 . Staying in sync Pruning never happens without prune when non interactive. 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 Jess's default for landing multiple PRs is sequential merging through the forge. Use [merge open prs](../merge open prs/SKILL.md): merge the parent first, then apply the repository's base update and verification requirements to the next PR. Do not turn a request to merge open PRs into one combined stack operation. Use the commands below only when the user requests a whole stack merge. Scope that merge with an argument: 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. base is the saved SHA of the parent branch that this branch was last known to contain. It may be older than the parent's current tip. needsRebase is true when the current parent tip is no longer an ancestor of the branch. Exit codes Code Meaning Recovery 0 Success (none) 1 Generic error Read stderr 2 Not in a stack gh stack init , or gh stack checkout <target 3 Rebase conflict Follow the Exit 3 recovery below 4 GitHub API failure Check gh auth status , retry 5 Invalid arguments Fix the invocation; see <command help 6 Disambiguation required Branch is in several stacks; check out a non shared branch 7 Rebase already in progress gh stack rebase continue or abort 8 Stack file locked Another gh stack process is writing; retry after ~5s 9 Stacked PRs unavailable Not enabled on the repository; tell the user 10 Modify recovery required gh stack modify abort Exit 3 recovery: After gh stack rebase : resolve the files, run git add , then gh stack rebase continue ; use gh stack rebase abort to restore the stack. After gh stack sync : the stack has already been restored. Run gh stack rebase to recreate the conflict, then resolve and continue as above. Constraints Stacks are strictly linear: one parent, at most one child. Use separate stacks for parallel work. There is no non interactive reorder or removal. Errors may suggest gh stack modify , but it is TUI only; restructure with unstack then init instead. PR titles and bodies are auto generated. Use gh pr edit afterwards to change them. checkout <branch name resolves against local stacks only. Use a stack or PR number to pull a stack down from GitHub. More detail gh stack <command help is authoritative for flags and arguments ( gh stack help <command prints the top level help instead). Read the reference that matches the task: references/stack design.md : before creating a stack, when deciding how many layers to use and what belongs in each. references/commands.md : when a command fails unexpectedly or you need its preconditions, side effects, atomicity, or ordering guarantees. references/troubleshooting.md : on a rebase conflict, after a squash merge, on local and remote divergence, or when restructuring a stack.

gh-stack