CLI Commands

Installation

gh extension install github/gh-stack

Requires the GitHub CLI (gh) v2.0+.

Authentication

The gh stack CLI requires OAuth authentication via gh auth login. Personal access tokens (PATs) are not supported.

---

Stack Management

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 branch names (prefix/01, prefix/02, …).

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 first branch upfront
gh stack init feature-auth

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

# Adopt or create multiple branches at once
gh stack init feature-auth feature-api feature-ui

# Set a prefix — prompts for a branch name suffix
gh stack init -p 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.

Flag	Description
-A, --all	Stage all changes (including untracked files); requires -m
-u, --update	Stage changes to tracked files only; requires -m
-m, --message <string>	Create a commit with this message before creating the branch

Note: -A and -u are mutually exclusive.

Examples:

# Create a branch by name
gh stack add api-routes

# Prompt for a branch name interactively
gh stack add

# Stage all changes, commit, and auto-generate the branch name
gh stack add -Am "Add login endpoint"

# Stage only tracked files, commit, and auto-generate the branch name
gh stack add -um "Fix auth bug"

# Commit already-staged changes and auto-generate the branch name
gh stack add -m "Add user model"

# Stage all changes, commit, and use an explicit branch name
gh stack add -Am "Add tests" test-layer

# Stage only tracked files, commit, and use an explicit branch name
gh stack add -um "Update docs" docs-layer

gh stack view

View the current stack.

gh stack view [flags]

Shows all branches in the stack, their ordering, PR links, and the most recent commit with a relative timestamp. Output is piped through a pager (respects GIT_PAGER, PAGER, or defaults to less -R).

Flag	Description
-s, --short	Compact output (branch names only)
--json	Output stack data as JSON

Examples:

gh stack view
gh stack view --short
gh stack view --json

gh stack checkout

Check out a stack from a pull request number or branch name.

gh stack checkout [<pr-number> | <branch>]

When a PR number is provided (e.g., 123), the command fetches the stack on GitHub, pulls the branches, and sets up the stack locally. If the stack already exists locally and matches, it switches to the branch. If the local and remote stacks have different compositions, you’ll be prompted to resolve the conflict.

When a branch name is provided, the command resolves it against locally tracked stacks only.

When run without arguments in an interactive terminal, shows a menu of all locally available stacks to choose from.

Examples:

# Check out a stack by PR number
gh stack checkout 42

# Check out a stack by branch name (local only)
gh stack checkout feature-auth

# Interactive — select from locally tracked stacks
gh stack checkout

gh stack modify

Interactively restructure the current stack.

gh stack modify [flags]

Opens an interactive terminal UI for restructuring a stack. All changes are staged in the TUI and applied together when you press Ctrl+S. Branches from merged PRs cannot be modified.

Flag	Description
--continue	Continue after resolving conflicts
--abort	Abort the modify session and restore the stack to its pre-modify state

Preconditions:

The command checks these conditions before opening the TUI:

1. Must have an active stack checked out locally
2. Working tree must be clean (no uncommitted changes)
3. No rebase in progress
4. No PR in the stack is queued for merge
5. Commit history must be linear (no merge commits, no diverged branches)

Operations:

Operation	Key	Effect
Drop	x	Remove branch and its commits from stack. Local branch and associated PR are preserved.
Fold down	d	Absorb commits into branch below (toward trunk). Folded branch removed from stack.
Fold up	u	Absorb commits into branch above (away from trunk). Folded branch removed from stack.
Insert below	i	Insert a new empty branch below the cursor (toward trunk).
Insert above	I	Insert a new empty branch above the cursor (away from trunk).
Move down	Shift+↓	Reorder branch down (toward trunk) in the stack
Move up	Shift+↑	Reorder branch up (away from trunk) in the stack
Rename	r	Rename the branch (opens inline prompt)
Undo	z	Undo the last staged action

Apply phase:

When you press Ctrl+S, the staged changes are applied by renaming branches, inserting new branches, folding/dropping branches, and running a cascading rebase to create a linear commit history with the desired stack state.

If a rebase conflict occurs, you can:

• Resolve conflicts, stage files, and run gh stack modify --continue
• Or run gh stack modify --abort to abort the operation and restore the stack to the pre-modify state

After modifying:

If a stack of PRs has been created on GitHub, run gh stack submit to push the updated branches and recreate the stack. The old stack is automatically replaced.

Examples:

# Open the interactive modify TUI
gh stack modify

# Continue after resolving a conflict
gh stack modify --continue

# Abort and restore to the previous state
gh stack modify --abort

gh stack unstack

Remove a stack from local tracking and delete it on GitHub. Also available as gh stack delete.

gh stack unstack [flags]

You must have a branch from the stack checked out locally. The command targets the active stack — the one that contains the currently checked out branch.

Deletes the stack on GitHub first, if it exists, then removes it from local tracking. If the remote deletion fails, the local state is left untouched so you can retry. Use --local to skip the remote deletion and only remove local tracking.

This is useful when you need to restructure a stack — remove a branch, insert a branch, reorder branches, rename branches, or make other large changes. After unstacking, use gh stack init to re-create the stack with the desired structure — existing branches are adopted automatically.

Flag	Description
--local	Only delete the stack locally (keep it on GitHub)

Examples:

# Delete the stack on GitHub and remove local tracking
gh stack unstack

# Only remove local tracking
gh stack unstack --local

---

Remote Operations

gh stack submit

Push all branches and create/update PRs and the stack on GitHub.

gh stack submit [flags]

Creates a Stacked PR for every branch in the stack, pushing branches to the remote. After creating PRs, submit automatically creates a Stack on GitHub to link the PRs together. If the stack already exists on GitHub (e.g., from a previous submit), new PRs are added to the existing stack.

When creating new PRs, you will be prompted to enter a title for each one. Press Enter to accept the default (branch name), or use --auto to skip prompting entirely. New PRs are created as drafts by default; use --open to create new PRs as ready for review and to mark existing PRs as ready for review.

Flag	Description
--auto	Use auto-generated PR titles without prompting
--open	Create new PRs as ready for review instead of drafts, and mark existing PRs as ready for review
--remote <name>	Remote to push to (defaults to auto-detected remote)

Examples:

gh stack submit
gh stack submit --auto
gh stack submit --open

gh stack sync

Fetch, rebase, push, and sync PR state in a single command.

gh stack sync [flags]

Performs a safe, non-interactive synchronization of the entire stack:

1. Fetch — fetches the latest changes from origin.
2. Fast-forward trunk — fast-forwards the trunk branch to match the remote (skips if diverged).
3. Cascade rebase — rebases all stack branches onto their updated parents (only if trunk moved). If a conflict is detected, all branches are restored to their original state, and you are advised to run gh stack rebase to resolve conflicts interactively.
4. Push — pushes all branches (uses --force-with-lease if a rebase occurred).
5. Sync PRs — syncs PR state from GitHub and reports the status of each PR.
6. Prune — in interactive terminals, prompts to delete local branches for merged PRs. Use --prune to prune automatically.

Flag	Description
--remote <name>	Remote to fetch from and push to (defaults to auto-detected remote)
--prune	Delete local branches for merged PRs

Examples:

gh stack sync

# Sync and automatically prune merged branches
gh stack sync --prune

gh stack rebase

Pull from remote and do a cascading rebase across the stack.

gh stack rebase [flags] [branch]

Fetches the latest changes from origin, then ensures each branch in the stack has the tip of the previous layer in its commit history. Rebases branches in order from trunk upward.

If a branch’s PR has been merged, the rebase automatically switches to --onto mode to correctly replay commits on top of the merge target.

If a rebase conflict occurs, the operation pauses and prints the conflicted files with line numbers. Resolve the conflicts, stage with git add, and continue with --continue. To undo the entire rebase, use --abort to restore all branches to their pre-rebase state.

Flag	Description
--downstack	Only rebase branches from trunk to the current branch
--upstack	Only rebase branches from the current branch to the top
--continue	Continue the rebase after resolving conflicts
--abort	Abort the rebase and restore all branches to their pre-rebase state
--remote <name>	Remote to fetch from (defaults to auto-detected remote)
--committer-date-is-author-date	Set the committer date to the author date during rebase. Alias: --preserve-dates

Argument	Description
[branch]	Target branch (defaults to the current branch)

Examples:

# Rebase the entire stack
gh stack rebase

# Only rebase branches below the current one
gh stack rebase --downstack

# Only rebase branches above the current one
gh stack rebase --upstack

# After resolving a conflict
gh stack rebase --continue

# Abort rebase and restore everything
gh stack rebase --abort

# Rebase and preserve committer date as author date
gh stack rebase --committer-date-is-author-date

gh stack push

Push all branches in the current stack to the remote.

gh stack push [flags]

Pushes every branch to the remote using --force-with-lease --atomic. This is a lightweight wrapper around git push that knows about all branches in the stack. It does not create or update pull requests — use gh stack submit for that.

Flag	Description
--remote <name>	Remote to push to (defaults to auto-detected remote)

Examples:

gh stack push
gh stack push --remote upstream

gh stack link

Link PRs into a stack on GitHub without local tracking.

gh stack link [flags] <branch-or-pr> <branch-or-pr> [...]

Creates or updates a stack on GitHub from branch names or PR numbers. This command does not create or modify any gh-stack local tracking state. It is designed for users who manage branches with other tools locally (e.g., jj, Sapling, git-town) and want to simply open a stack of PRs.

Arguments are provided in stack order (bottom to top). Branch arguments are automatically pushed to the remote before creating or looking up PRs. For branches that already have open PRs, those PRs are used. For branches without PRs, new PRs are created automatically with the correct base branch chaining. Existing PRs whose base branch doesn’t match the expected chain are corrected automatically.

If the PRs are not yet in a stack, a new stack is created. If some of the PRs are already in a stack, the existing stack is updated to include the new PRs. Existing PRs are never removed from a stack — the update is additive only.

Flag	Description
--base <branch>	Base branch for the bottom of the stack (default: main)
--open	Mark new and existing PRs as ready for review
--remote <name>	Remote to push to (defaults to auto-detected remote)

Examples:

# Link branches into a stack (pushes, creates PRs, creates stack)
gh stack link feature-auth feature-api feature-ui

# Link existing PRs by number
gh stack link 10 20 30

# Add branches to an existing stack of PRs
gh stack link 42 43 feature-auth feature-ui

# Use a different base branch and mark PRs as ready for review
gh stack link --base develop --open feat-a feat-b feat-c

---

Navigation

Move between branches in the current stack without having to remember branch names. The bottom of the stack is the branch closest to the trunk, and the top is furthest from it. up moves away from trunk; down moves toward it.

All navigation commands clamp to the bounds of the stack — moving up from the top or down from the bottom is a no-op with a message.

gh stack switch

Interactively switch to another branch in the stack.

gh stack switch

Shows an interactive picker listing all branches in the current stack, ordered from top (furthest from trunk) to bottom (closest to trunk) with their position number. Select a branch to check it out.

Requires an interactive terminal.

Examples:

gh stack switch
#    → Select a branch in the stack to switch to
#      5. frontend
#      4. api-endpoints
#      3. auth-layer
#      2. db-schema
#      1. config-setup

gh stack up

Move up toward the top of the stack (away from trunk).

gh stack up [n]

Moves up n branches (default 1). If you’re on the trunk branch, up moves to the first stack branch.

Examples:

gh stack up          # move up one layer
gh stack up 3        # move up three layers

gh stack down

Move down toward the bottom of the stack (toward trunk).

gh stack down [n]

Moves down n branches (default 1).

Examples:

gh stack down        # move down one layer
gh stack down 2      # move down two layers

gh stack top

Jump to the top of the stack.

gh stack top

Checks out the branch furthest from the trunk.

gh stack bottom

Jump to the bottom of the stack.

gh stack bottom

Checks out the branch closest to the trunk.

gh stack trunk

Jump to the trunk branch.

gh stack trunk

Checks out the trunk branch of the current stack (e.g., main). You must be on a branch that is part of a stack.

---

Utilities

gh stack alias

Create a short command alias so you can type less.

gh stack alias [flags] [name]

Installs a small wrapper script into ~/.local/bin/ that forwards all arguments to gh stack. The default alias name is gs, but you can choose any name by passing it as an argument. After setup, you can run gs push instead of gh stack push.

On Windows, automatic alias creation is not supported — the command prints manual instructions for creating a batch file or PowerShell function.

Flag	Description
--remove	Remove a previously created alias

Examples:

# Create the default alias (gs)
gh stack alias
#    → now "gs push", "gs view", etc. all work

# Create a custom alias
gh stack alias gst

# Remove an alias
gh stack alias --remove
gh stack alias --remove gst

gh stack feedback

Share feedback about gh-stack.

gh stack feedback [title]

Opens a GitHub Discussion in the gh-stack repository to submit feedback. Optionally provide a title for the discussion post.

Examples:

gh stack feedback
gh stack feedback "Support for reordering branches"

---

Exit Codes

Code	Meaning
0	Success
1	Generic error
2	Not in a stack / stack not found
3	Rebase conflict
4	GitHub API failure
5	Invalid arguments or flags
6	Disambiguation required (branch belongs to multiple stacks)
7	Rebase already in progress
8	Stack is locked by another process
9	Stacked PRs not enabled for this repository