Skip to content
Skills Library
Programming · Automation

gh-stack

/gh-stack

Manages stacked PRs and splits multi-part work into reviewable branches with 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 a user mentions a stack, branch layers, dependent PRs, or gh stack; or when a stack is checked out.

Repository
nix ↗
Licence
MIT
Last repository change
11.10.2026

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
4
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 11.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Manages stacked PRs and splits multi-part work into reviewable branches with 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 a user mentions a stack, branch layers, dependent PRs, or gh stack; or when a stack is checked out.

Original author description

Manages stacked PRs and splits multi-part work into reviewable branches with 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 a user mentions a stack, branch layers, dependent PRs, or gh stack; or when a stack is checked out.

How it works

  1. Local stacked-worktree workflow
  2. Setup
  3. Non-interactive use
  4. Branch placement
  5. Core loop
  6. Staying in sync
  7. Merging
  8. Reading state
  9. Exit codes
  10. Constraints
Original SKILL.md headings · 199 lines, 1,570 words
SKILL.md preview
---
name: gh-stack
description: >
  Manages stacked PRs and splits multi-part work into reviewable branches with 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 a user mentions a stack,
  branch layers, dependent PRs, or gh stack; or when a stack is checked out.
metadata:
  author: github
  version: "0.1.0"
---

## Local stacked-worktree workflow

These instructions override the same-checkout workflows below. Every active pull request branch in a stack must have its own sibling worktree and tmux session.

Plan the complete stack first, then build it bottom-up. Finish and commit each parent layer before creating its child so the child starts from the parent's completed tip. Give each layer a focused prompt describing only that pull request's concern.

Invoke the `tmux-pi` skill for every layer. Create the bottom layer from `main`, then create each child from its parent:

```bash
tmux-pi --task-slug '<task>' --prompt-file '<prompt-file>' --worktree '<bottom>' --model "openai/gpt-6.1-sol" --thinking "high"
tmux-pi --task-slug '<task>' --prompt-file '<prompt-file>' --worktree '<child>' --source-ref '<parent>' --model "openai/gpt-6.1-sol" --thinking "high"
```

Follow the skill's listener and supervision protocol before moving to the next layer.

Preserve every existing stack entry, including merged and closed PRs, unless the user explicitly asks to remove it. Before unstacking, rebuilding, or relinking a stack, inspect the complete remote stack. If the intended operation would omit, reorder, or split existing entries, stop and ask rather than proceeding.

Because the branches live in separate worktrees, manage stack membership without local gh-stack tracking:

```bash
gh stack link --remote origin '<bottom>' '<middle>' '<top>'
```

Do not use `gh stack init`, `add`, `checkout`, navigation, `rebase`, or `sync` for this workflow. Rebase changed descendants from within their own worktrees, bottom-up, then rerun `gh stack link`.


# 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 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 --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

Scope the 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 | — |
| 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. Note that
`gh stack help <command>` does **not** work — it prints the top-level help.

Open the reference whose trigger matches the task; no need to preload all three.

- `references/stack-design.md` — read before creating a stack, when deciding how many layers to
  use, what belongs in each one, or whether work belongs in a new stack.
- `references/commands.md` — read when a command fails unexpectedly or you need its preconditions,
  side effects, atomicity, or ordering guarantees.
- `references/troubleshooting.md` — read on a rebase conflict, after a squash-merge, on local and
  remote divergence, when restructuring a stack, or when driving stacks from another tool.
Files in this package (4)
  • SKILL.md 10 KB
  • references/commands.md 9 KB
  • references/stack-design.md 4 KB
  • references/troubleshooting.md 7 KB

Versions

RepositoryScoreLicence
This page · richardgill/nix100MIT
remotion-dev/remotion100MIT
cherryhq/cherry-studio100AGPL-3.0
vercel/next.js100MIT
nicknisi/dotfiles100MIT
github/gh-stack100MIT
richardgill/nix100MIT
richardgill/nix100MIT
richardgill/nix100MIT

Database snapshot: 13.11.2026 · package version 6b3a069167c5 (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
    Manages dependent branch stacks and stacked pull requests using safe Git topology rules. Triggers on: "create stacked PRs", "publish this stack", "sync my PR stack", "rebase this stack", "merge the stack", "retarget child PRs", "split this branch into stacked PRs", "validate…
  • 100jabr
    Structure a feature as a stack of small, dependent pull requests and manage it end-to-end with plain git + the GitHub gh CLI. Use when the user wants to break a large feature or change into stacked / chained PRs, create or manage a PR stack, restack (rebase) dependent branches…
  • 100stacking-prs
    Create and manage GitHub native Stacked PRs in this repo with the `gh stack` CLI. Use when asked to stack PRs, split a large change into a stack, add a layer to a stack, restack or rebase a stack, adopt existing branches or PRs into a stack, check out someone else's stack, or…
  • 86stacked-branches
    Build, submit, sync and merge a stack of dependent pull requests on GitHub (`gh stack`) or Gitea (`git-spice`/`gs`). Use when a follow-up needs its own pull request on top of the effort's, when the user asks for a stack, when a `warp` builds past a blocked step, or when a…
  • 100stacked-prs
    Run a stack of pull requests on GitHub with `gh stack`: create, grow, submit, sync, land, repair, and cut a per-layer worktree with its handoff. Use when the user talks about stacked PRs, a stack or pile of PRs, `gh stack`, wants to split a large change into reviewable PRs that…
  • 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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.