github-gh-stack

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...]

Initializes a new stack locally. In interactive mode (no arguments), prompts for a branch name and offers to use the current branch as the first layer. If a branch name contains slashes (e.g., feat/api), prompts if you would like to use a prefix (e.g., feat/) for all branches in the stack.

When explicit branch names are given, existing branches are adopted automatically and any missing branches are created. 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)
-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 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.

You can optionally stage changes and create a commit as part of the add flow. When -m is provided without an explicit branch name, the branch name is auto-generated. If the stack was created with --numbered, auto-generated names use numbered format (prefix/01, prefix/02); otherwise, date+slug format is used (e.g., prefix/2025-03-24-add-login).