Gh Stack

gh-stack

gh stack is a GitHub CLI extension for managing stacked branches and pull requests. A stack is an ordered list of branches where each branch builds on the one below it, rooted on a trunk branch (typically the repo's default branch). Each branch maps to one PR whose base is the branch below it, so reviewers see only the diff for that layer.

main (trunk)
 └── feat/auth-layer     → PR #1 (base: main)               - bottom (closest to trunk)
  └── feat/api-endpoints → PR #2 (base: feat/auth-layer)
   └── feat/frontend     → PR #3 (base: feat/api-endpoints) - top (furthest from trunk)

The bottom of the stack is the branch closest to the trunk, and the top is the branch furthest from the trunk. 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 to use this skill

Use this skill when the user wants to:

• Break a large change into a chain of small, reviewable PRs
• Create, rebase, push, or sync a stack of dependent branches
• Navigate between layers of a branch stack
• View the status of stacked PRs
• Tear down and rebuild a stack to remove, reorder, or rename branches

Prerequisites

The GitHub CLI (gh) v2.0+ must be installed and authenticated. Install the extension with:

gh extension install github/gh-stack

Official CLI reference: https://github.github.com/gh-stack/reference/cli/

Bundled workflow reference

For the local single-worktree-lane workflow, read references/single-worktree-lane.md in this skill directory. It explains the preferred model for agent work:

• one worktree = one isolated agent lane / deliverable workspace
• one stack inside that worktree = multiple review branches for the same deliverable or

tightly related deliverable group

• one branch = one review unit, represented by commits, not by a remembered file list

Use that reference for methodology and examples; use this SKILL.md for command rules and non-interactive gh stack usage.

Before using gh stack, configure git to prevent interactive prompts:

git config rerere.enabled true           # remember conflict resolutions (skips prompt on init)
git config remote.pushDefault origin     # if multiple remotes exist (skips remote picker)

Agent rules

All gh stack commands must be run non-interactively. Every command invocation must include the flags and positional arguments needed to avoid prompts, TUIs, and interactive menus. If a command would prompt for input, it will hang indefinitely.

1. Always supply branch names as positional arguments to init, add, and checkout. Running these commands without arguments triggers interactive prompts.
2. When a prefix is set, pass only the suffix to add. gh stack add auth with prefix feat → feat/auth. Passing feat/auth creates feat/feat/auth.
3. Always use --auto with gh stack submit to auto-generate PR titles. Without --auto, submit prompts for a title for each new PR.
4. Always use --json with gh stack view. Without --json, the command launches an interactive TUI that cannot be operated by agents. There is no other appropriate flag — always pass --json.
5. Use --remote when multiple remotes are configured, or pre-configure git config remote.pushDefault origin. Without this, push, submit, sync, link, and checkout trigger an interactive remote picker.
6. Avoid branches shared across multiple stacks. If a branch belongs to multiple stacks, commands exit with code 6. Check out a non-shared branch first.
7. Plan your stack layers by dependency order before writing code. Foundational changes (models, APIs, shared utilities) go in lower branches; dependent changes (UI, consumers) go in higher branches. Think through the dependency chain before running gh stack init.
8. Use standard git add and git commit for staging and committing. This gives you full control over which changes go into each branch. The -Am shortcut is available but should not be the default approach—stacked PRs are most effective when each branch contains a deliberate, logical set of changes.
9. Navigate down the stack when you need to change a lower layer. If you're working on a frontend branch and realize you need API changes, don't hack around it at the current layer. Navigate to the appropriate branch (gh stack down, gh stack checkout, or gh stack bottom), make and commit the changes there, run gh stack rebase --upstack, then navigate back up to continue.
10. Use gh stack link for external tool workflows. When branches are managed by an external tool (jj, Sapling, etc.), use gh stack link branch-a branch-b. link does not rely on local tracking state and is intended for API-driven PR and stack management. Always provide at least 2 branch names or PR numbers.

Never do any of the following — each triggers an interactive prompt or TUI that will hang:

• ❌ gh stack view or gh stack view --short — always use gh stack view --json
• ❌ gh stack submit without --auto — always use gh stack submit --auto
• ❌ gh stack init without branch arguments — always provide branch names
• ❌ gh stack add without a branch name — always provide a branch name
• ❌ gh stack checkout without an argument — always provide a PR number or branch name
• ❌ gh stack checkout when a different local stack already exists on those branches — this triggers an unbypassable conflict resolution prompt; use gh stack unstack first to remove the local stack, then retry the checkout

Thinking about stack structure

Each branch in a stack should represent a discrete, logical unit of work that can be reviewed independently. The changes within a branch should be cohesive—they belong together and make sense as a single PR.

Dependency chain

Stacked branches form a dependency chain: each branch builds on the one below it. This means foundational changes must go in lower (earlier) branches, and code that depends on them goes in higher (later) branches.

Plan your layers before writing code. For example, a full-stack feature might be structured like this (use branch names relevant to your actual task, not these generic ones):

main (trunk)
 └── feat/data-models    ← shared types, database schema
  └── feat/api-endpoints ← API routes that use the models
   └── feat/frontend-ui  ← UI components that call the APIs
    └── feat/integration ← tests that exercise the full stack

This is illustrative — choose branch names and layer boundaries that reflect the specific work you're doing. The key principle is: if code in one layer depends on code in another, the dependency must be in the same branch or a lower one.

Branch naming

Prefer initializing stacks with a prefix (-p). Prefixes group branches under a namespace (e.g., feat/auth, feat/api) and keep branch names clean and consistent. When a prefix is set, pass only the suffix to subsequent add calls — the prefix is applied automatically. Without a prefix, you'll need to pass the full branch name each time.

Staging changes deliberately

The main reason to use git add and git commit directly is to control which changes go into which branch. When you have multiple files in your working tree, you can stage a subset for the current branch, commit them, then create a new branch and stage the rest there:

# You're on feat/data-models with several new files in your working tree.
# Stage only the model files for this branch:
git add internal/models/user.go internal/models/session.go
git commit -m "Add user and session models"

git add db/migrations/001_create_users.sql
git commit -m "Add user table migration"

# Now create a new branch for the API layer and stage the API files there:
gh stack add api-routes # created & switched to feat/api-routes branch
git add internal/api/routes.go internal/api/handlers.go
git commit -m "Add user API routes"

This keeps each branch focused on one concern. Multiple commits per branch are fine — the key is that all commits in a branch relate to the same logical concern, and changes that belong to a different concern go in a different branch.

When to create a new branch

Create a new branch (gh stack add) when you're starting a different concern that depends on what you've built so far. Signs it's time for a new branch:

• You're switching from backend to frontend work
• You're moving from core logic to tests or documentation
• The next set of changes has a different reviewer audience
• The current branch's PR is already large enough to review

One stack, one story

Think of a stack from the reviewer's perspective: the stack of PRs should tell a cohesive story about a feature or project. A reviewer should be able to read the PRs in sequence and understand the progression of changes, with each PR being a small, logical piece of the whole.

When to use a single stack: All the branches are part of the same feature, project, or closely related effort. Even if the work spans multiple concerns (models, API, frontend), they're all building toward the same goal.

When to create a separate stack: The work is unrelated to your current stack — a different feature, a bug fix in an unrelated area, or an independent refactor. Don't mix unrelated work into a single stack just because you happen to be working on both. Start a new stack with gh stack init or switch to an existing stack with gh stack checkout for each distinct effort.

Small, incidental fixes (e.g., fixing a typo you noticed) can go in the current stack if they're trivial. But if a change grows into its own project, it deserves its own stack.

Quick reference

| Task | Command | |------|---------| | Create a stack (recommended) | gh stack init -p feat auth | | Create a stack without prefix | gh stack init auth | | Adopt existing branches | gh stack init --adopt branch-a branch-b | | Set custom trunk | gh stack init --base develop branch-a | | Add a branch to stack (suffix only if prefix set) | gh stack add api-routes | | Add branch + stage all + commit | gh stack add -Am "message" api-routes | | Push branches to remote | gh stack push | | Push to specific remote | gh stack push --remote origin | | Push branches + create PRs | gh stack submit --auto | | Create PRs as drafts | gh stack submit --auto --draft | | Sync (fetch, rebase, push) | gh stack sync | | Sync with specific remote | gh stack sync --remote origin | | Rebase entire stack | gh stack rebase | | Rebase upstack only | gh stack rebase --upstack | | Continue after conflict | gh stack rebase --continue | | Abort rebase | gh stack rebase --abort | | View stack details (JSON) | gh stack view --json | | Switch branches up/down in stack | gh stack up [n] / gh stack down [n] | | Switch to top/bottom branch | gh stack top / gh stack bottom | | Check out by PR | gh stack checkout 42 | | Check out by branch (local only) | gh stack checkout feature-auth | | Tear down a stack to restructure it | gh stack unstack |

---

Workflows

End-to-end: create a stack from scratch

# 1. Initialize a stack with the first branch
gh stack init -p feat auth
# → creates feat/auth and checks it out

# 2. Write code for the first layer (auth)
cat > auth.go  auth_test.go  api.go  frontend.go  **Shortcut:** If you prefer a faster flow, `gh stack add -Am "message" branch-name` combines staging, committing, and branch creation into one command. This is useful for single-commit layers but bypasses deliberate staging.

### Making mid-stack changes

This is a critical workflow for agents. When you're working on a higher layer and realize you need to change something in a lower layer (e.g., you're building frontend components but need to add an API endpoint), **navigate down to the correct branch, make the change there, and rebase**.

```bash
# You're on feat/frontend but need to add an API endpoint

# 1. Navigate to the API branch
gh stack down
# or: gh stack checkout feat/api-routes

# 2. Make the change where it belongs
cat > users_api.go  auth.go >>>>>> markers
#    - Edit files to resolve conflicts
#    - Stage resolved files:
git add path/to/resolved-file.go

# 3. Continue the rebase
gh stack rebase --continue

# 4. If another conflict occurs, repeat steps 2-3

# 5. If unable to resolve, abort to restore everything
gh stack rebase --abort

Parsing --json output

# Get stack state as JSON
output=$(gh stack view --json)

# Check if any branch needs a rebase, and rebase if so
needs_rebase=$(echo "$output" | jq '[.branches[] | select(.needsRebase == true)] | length')
if [ "$needs_rebase" -gt 0 ]; then
  echo "Branches need rebase, rebasing stack..."
  gh stack rebase
fi

# Get all open PR URLs
echo "$output" | jq -r '.branches[] | select(.pr.state == "OPEN") | .pr.url'

# Find merged branches
echo "$output" | jq -r '.branches[] | select(.isMerged == true) | .name'

# Get the current branch
echo "$output" | jq -r '.currentBranch'

# Check if the stack is fully merged (all branches merged)
echo "$output" | jq '[.branches[] | .isMerged] | all'

Restructure a stack (remove a branch, reorder, or rename)

Use unstack to tear down the stack, make structural changes, then re-init:

# 1. Remove the stack (locally and on GitHub)
gh stack unstack

# 2. Make structural changes — e.g. delete a branch, reorder, rename
git branch -m old-branch-1 new-branch-1

# 3. Re-create the stack with the new structure
gh stack init --base main --adopt new-branch-1 new-branch-2 new-branch-3

---

Commands

Initialize a stack — gh stack init

Creates a new stack. Always provide at least one branch name as a positional argument — running without branch arguments triggers interactive prompts that agents cannot use.

gh stack init [flags] 

# Set a branch prefix (recommended — subsequent `add` calls only need the suffix)
gh stack init -p feat auth
# → creates feat/auth

# Multi-part prefix (slashes are fine — suffix-only rule still applies)
gh stack init -p monalisa/billing auth
# → creates monalisa/billing/auth

# Create a stack with new branches (no prefix — use full branch names)
gh stack init branch-a branch-b branch-c

# Use a different trunk branch
gh stack init --base develop branch-a branch-b

# Adopt existing branches into a stack
gh stack init --adopt branch-a branch-b branch-c

| Flag | Description | |------|-------------| | -b, --base | Trunk branch (defaults to the repo's default branch) | | -a, --adopt | Adopt existing branches instead of creating new ones | | -p, --prefix | Branch name prefix. Subsequent add calls only need the suffix (e.g., with -p feat, gh stack add auth creates feat/auth) |

Behavior:

• Using -p is recommended — it simplifies branch naming for subsequent add calls
• Creates any branches that don't already exist (branching from the trunk branch)
• In --adopt mode: validates all branches exist, rejects if any is already in a stack or has an existing PR
• Checks out the last branch in the list
• Enables git rerere so conflict resolutions are remembered across rebases. On first run in a repo, this may trigger a confirmation prompt — pre-configure with git config rerere.enabled true to avoid it

---

Add a branch — gh stack add

Add a new branch on top of the current stack. Must be run while on the topmost branch (or the trunk if the stack has no branches yet). Always provide a branch name — running without one triggers an interactive prompt.

gh stack add [flags] 

Recommended workflow — create the branch, then use standard git:

# Create a new branch and switch to it (just the suffix — prefix is applied automatically)
gh stack add api-routes

# Write code, stage deliberat

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [zazzcode](https://github.com/zazzcode)
- **Source:** [zazzcode/zazz-skills](https://github.com/zazzcode/zazz-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.