GitHub Stacked PRs
A GitHub CLI extension for managing stacked branches and pull requests.
Stacked PRs break large changes into a chain of small, reviewable pull requests that build on each other. gh stack automates the tedious parts — creating branches, keeping them rebased, setting correct PR base branches, and navigating between layers.
[!NOTE]
Stacked PRs is currently in private preview. This CLI and the referenced functionality will not work unless the feature has been enabled for your repository.
You can sign up for the waitlist at gh.io/stacksbeta.
Installation
gh extension install github/gh-stack
Requires the GitHub CLI (gh) v2.0+.
AI agent integration
Install the gh-stack skill so your AI coding agent knows how to work with stacked PRs and the gh stack CLI:
gh skill install github/gh-stack
Quick start
# Start a new stack (creates and checks out the first branch)
gh stack init
# ... make commits on the first branch ...
# Add another branch on top
gh stack add api-endpoints
# ... make commits ...
# Push all branches
gh stack push
# View the stack
gh stack view
# Open a stack of PRs
gh stack submit
How it works
A stack is an ordered list of branches where each branch builds on the one below it. The bottom of the stack is based on a trunk branch (typically main).
frontend → PR #3 (base: api-endpoints) ← top
api-endpoints → PR #2 (base: auth-layer)
auth-layer → PR #1 (base: main) ← bottom
─────────────
main (trunk)
The bottom of the stack is the branch closest to the trunk, and the top is the branch furthest from it. Each branch inherits from the one below it. Navigation commands (up, down, top, bottom) follow this model: up moves away from trunk, down moves toward it.
When you submit, gh stack creates one PR per branch and links them together as a Stack on GitHub. Each PR's base is set to the branch below it in the stack, so reviewers see only the diff for that layer.
Local tracking
Stack metadata is stored in .git/gh-stack (a JSON file, not committed to the repo). This tracks which branches belong to which stack and their ordering. Rebase state during interrupted rebases is stored separately in .git/gh-stack-rebase-state.
Commands
gh stack init
Initialize a new stack in the current repository.
gh stack init [flags] [branches...]
Creates an entry in .git/gh-stack to track stack state. In interactive mode (no arguments), prompts you to name branches and offers to use the current branch as the first layer. In interactive mode, you'll also be prompted to set an optional branch prefix (unless adopting existing branches). When a prefix is set, branch names you enter are automatically prefixed. When explicit branch names are given, creates any that don't already exist (branching from the trunk). The trunk defaults to the repository's default branch unless overridden with --base.
Use --numbered with --prefix to enable auto-incrementing numbered branch names (prefix/01, prefix/02, …). Without --numbered, you'll always be prompted to provide a meaningful branch name.
Enables git rerere automatically so that conflict resolutions are remembered across rebases.
| Flag | Description |
|---|
-b, --base <branch> | Trunk branch for the stack (defaults to the repository's default branch) |
-a, --adopt | Adopt existing branches into a stack instead of creating new ones |
-p, --prefix <string> | Set a branch name prefix for the stack |
-n, --numbered | Use auto-incrementing numbered branch names (requires --prefix) |
Examples:
# Interactive — prompts for branch names
gh stack init
# Non-interactive — specify branches upfront
gh stack init feature-auth feature-api feature-ui
# Use a different trunk branch
gh stack init --base develop feature-auth
# Adopt existing branches into a stack
gh stack init --adopt feature-auth feature-api
# Set a prefix — you'll be prompted for a branch name
gh stack init -p feat
# → prompts "Enter a name for the first branch (will be prefixed with feat/)"
# → type "auth" → creates feat/auth
# Use numbered auto-incrementing branch names
gh stack init -p feat --numbered
# → creates feat/01 automatically
gh stack add
Add a new branch on top of the current stack.
gh stack add [flags] [branch]
Creates a new branch at the current HEAD, adds it to the top of the stack, and checks it out. Must be run while on the topmost branch of a stack. If no branch name is given, prompts for one.