跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

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 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add iuhoay/skills --skill gh-stack

技能说明


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 runNever run bareWhy
gh stack view --jsongh stack viewopens a TUI under a PTY
gh stack submit --autogh stack submitprompts for a title per new PR
gh stack merge <target> --yesgh pr mergegh pr merge cannot merge a stack
gh stack init <branch>...gh stack initprompts for branch names
gh stack add <branch>gh stack addprompts for a name, and fails even when piped
gh stack checkout <target>gh stack checkoutopens a selection menu
gh stack up / down / top / bottomgh stack switchswitch is menu-only
—gh stack modifyTUI-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.
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
阅读完整来源 ↗