Programming · Planning
gh-stack
/gh-stack
Use when working in a checked-out PR stack, handling dependent PRs or branch layers, or planning to split work into stacked PRs.
For whom
Assessment and security
100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
- Files in this package
- 5
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 1
Deprecation
No signals detected. Repository changed on 09.10.2026, without references to retired models or APIs.
Licence
GPL-3.0, otwarta.
What it does and when to use it
Use when working in a checked-out PR stack, handling dependent PRs or branch layers, or planning to split work into stacked PRs.
Original author description
Use when working in a checked-out PR stack, handling dependent PRs or branch layers, or planning to split work into stacked PRs.
How it works
- Setup
- Non-interactive use
- Branch placement
- Core loop
- Staying in sync
- Merging
- Reading state
- Exit codes
- Constraints
- More detail
Original SKILL.md headings · 177 lines, 1,361 words
SKILL.md preview
---
name: gh-stack
description: "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:
```
(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
```bash
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
```
## 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.
```bash
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
```bash
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`.
## Staying in sync
```bash
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. 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:
```bash
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, isMerged, isQueued, needsRebase
branches[].pr number, url, state ("OPEN" | "MERGED" | "QUEUED"); absent when no PR exists
```
`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.
Files in this package (5)
- SKILL.md 8 KB
- agents/openai.yaml 1 KB
- references/commands.md 9 KB
- references/stack-design.md 4 KB
- references/troubleshooting.md 7 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · jssblck/agents | 100 | GPL-3.0 |
| remotion-dev/remotion | 100 | MIT |
| cherryhq/cherry-studio | 100 | AGPL-3.0 |
| vercel/next.js | 100 | MIT |
| nicknisi/dotfiles | 100 | MIT |
| github/gh-stack | 100 | MIT |
| richardgill/nix | 100 | MIT |
| richardgill/nix | 100 | MIT |
| richardgill/nix | 100 | MIT |
Database snapshot: 13.11.2026 · package version df4eb49e87ea (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100stacked-prs
Open, update and merge pull requests that depend on each other as a GitHub stack, with the gh stack extension. Use whenever a change builds on another pull request that hasn't merged yet, when splitting a large change into reviewable layers, when a stacked PR needs rebasing… - 90stacked-prs
Design and operate GitHub stacked pull requests with the official github/gh-stack CLI. Use when deciding whether dependent work should be a stack, splitting work into valid layers, or creating, reviewing, updating, handing off, merging, cleaning up, or recovering a stack. Do not… - 100stacked-prs
Work with GitHub stacked pull requests (gh stack) in the team's repos. Put a branch on the right stack, commit, push and open its PR with the "Stacked on" banner, fix a merge conflict on the one branch that has it, and walk a stack bottom to top. Use whenever the user says "on… - 100stacked-delivery
Plan, create, or maintain dependent pull requests with explicit branch bases and per-layer evidence. Use when one delivery needs multiple ordered PRs rather than a single PR or independent tickets. - 100stacked-prs
GitHub's native stacked pull requests and the `gh stack` CLI. Covers creating a stack, editing a layer, restacking after a merge, and merging part or all of a stack. Use whenever the user mentions stacked PRs, a PR stack, GitHub stacks, dependent PRs, or `gh stack`, when… - 100merging-pr-stack
Use when merging a stack of stacked PRs with jj. Triggered by phrases like "merge the PR stack", "merge the stacked PRs", "land these PRs", or "merge the stack into main".