stacked-prs
Break a large change into a chain of small, dependent pull requests using GitHub stacked pull requests and the gh stack CLI extension. Use this skill whenever the user mentions stacked PRs, stacked pull requests, a PR stack, stacking branches or commits, gh stack, splitting a large pull request into smaller reviewable PRs, chained or dependent pull requests, building new work on top of an unmerged PR, or shipping one task per PR from a larger effort.
dgalarza · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add dgalarza/agent-skills --skill stacked-prs技能说明
name: stacked-prs description: Break a large change into a chain of small, dependent pull requests using GitHub stacked pull requests and the gh stack CLI extension. Use this skill whenever the user mentions stacked PRs, stacked pull requests, a PR stack, stacking branches or commits, gh stack, splitting a large pull request into smaller reviewable PRs, chained or dependent pull requests, building new work on top of an unmerged PR, or shipping one task per PR from a larger effort.
Stacked Pull Requests
Break a large code change into a chain of small, dependent pull requests that can be reviewed and merged independently, using the gh stack extension for GitHub CLI. Each pull request (PR) contains one focused change, reviewers see only that layer's diff, and GitHub links the PRs together as a stack with a stack map and per-layer navigation.
Source docs: About stacked pull requests · Quickstart · Managing stacks
This feature is in public preview and may need to be enabled for the repository. If commands fail with exit code 9 ("stacked pull requests are not enabled"), report that to the user rather than working around it.
How stacks work
A stack is two or more PRs in the same repository where the bottom PR targets the trunk (usually the default branch) and every PR above it targets the branch of the PR below:
┌── feat/frontend → PR #3 (base: feat/api-endpoints) ← top
┌── feat/api-endpoints → PR #2 (base: feat/auth-layer)
┌── feat/auth-layer → PR #1 (base: main) ← bottom
main (trunk)
The key principle: if code in one layer depends on code in another, the dependency must live in the same branch or a lower one. This drives every layering decision:
- Foundational changes go low: shared types, database schema, core logic, configuration.
- Code that depends on them goes high: API routes, UI components, tests that exercise the whole thing.
- Start a new layer when you switch to a different concern (backend → frontend, core logic → tests) or when the current branch is already large enough to review.
Layer well up front. Restructuring a stack later is possible but costs a restructure cycle (see "Restructuring a stack" below), while adding the next layer on top is always cheap.
Constraints to know before starting:
- All branches must be in the same repository. Cross-fork stacks are not supported.
- Not supported in GitHub Desktop. Works in GitHub CLI, the GitHub website, GitHub Mobile, and via REST/GraphQL/webhooks.
- CI checks and branch protection rules for the trunk run and are enforced on every PR in the stack, not just the bottom one.
Prerequisites and setup
Requires GitHub CLI (gh) 2.90.0 or later, Git 2.20 or later, and authentication via gh auth login.
Install the extension once per machine:
gh extension install github/gh-stack
The extension reuses gh authentication — no separate login. gh stack init also enables git rerere automatically, so conflict resolutions are remembered across rebases.
Core workflow
-
Initialize the stack from the repository root. This creates a tracking entry and the first branch.
gh stack init # interactive: prompts for a branch name gh stack init feature-auth # non-interactive: name the first branch gh stack init --base develop feature-auth # target a non-default trunkExisting branches are adopted automatically; missing ones are created.
gh stack init b1 b2 b3builds the whole stack at once. -
Work and commit on the current branch with normal Git commands.
-
Add a layer when the next logical unit of work starts. Run this from the topmost branch:
gh stack add api-routes gh stack add -Am "Add login endpoint" # stage all + commit + branch in one stepThe
-Amshorthand has a useful quirk: if the current branch has no commits yet, the commit lands on the current branch; if it already has commits, a new branch is created on top. Omitting the branch name with-mauto-generates one like03-24-add_login— prefer explicit names. -
Push all branches:
gh stack push -
Create and link the PRs:
gh stack submitThis pushes branches, creates a PR per branch with the correct base, and links them as a stack on GitHub. Re-running it updates existing PRs and adds new branches to the existing stack; if every PR has merged, it starts a fresh stack rooted at the trunk.
-
Inspect the stack at any time:
gh stack view --short # one line per branch gh stack view --json # machine-readable
Non-interactive and agent guidance
Several commands open full-screen interactive editors. In a non-interactive terminal (or as an agent driving a shell), behavior changes in ways that matter:
- Inspecting: always use
gh stack view --shortor--json. Baregh stack viewopens a full-screen UI in an interactive terminal. Exit code 2 means the current branch is not in a stack — useful for detecting stack state. - Submitting:
gh stack submitin a non-interactive terminal behaves like--auto: it skips the editor and uses auto-generated titles. New PRs are created as drafts unless you pass--open. Drafts are usually the right default for agent-authored work; pass--openwhen the user wants PRs ready for review immediately. - Restructuring:
gh stack modifyandgh stack switchare interactive-only TUIs. Do not attempt to drive them. Use the non-interactive restructure pattern below instead. - Syncing:
gh stack syncaborts (exiting successfully, pushing nothing) when local and remote stacks have diverged