gh-stack

gh stack command [options]

gh stack is GitHub's CLI extension for stacked pull requests. A stack is an ordered chain of branches rooted on a trunk (usually main). The bottom branch is the one closest to the trunk; the top is the furthest from it. Each pull request uses the branch below it as its base, so a reviewer sees only that layer.Install the extension with gh extension install github/gh-stack. It needs GitHub CLI 2.0 or later, already authenticated with gh auth login. gh stack init also turns on git rerere so conflict resolutions are remembered.Local membership and order are stored in .git/gh-stack, which is not committed. Interrupted rebase state is kept in .git/gh-stack-rebase-state. On submit, the extension pushes the branches, opens one pull request per branch, and links them as a stack on GitHub.up moves away from the trunk and down moves toward it. Navigation stops at the ends of the stack. From the trunk, up checks out the first stack branch.submit in a terminal opens an editor for titles and descriptions. Ctrl+S submits the selected branches; Ctrl+X drops a branch and every branch above it. Outside a terminal, or with --auto, titles are generated and new pull requests are created as drafts unless --open is set. If every pull request in the stack is already merged, submit starts a new stack for the remaining branches.sync fetches, fast-forwards the trunk when it can, rebases only if the trunk moved, pushes (with --force-with-lease after a rebase), and refreshes pull request state. Opening new pull requests stays with submit. When the local and remote stacks have diverged, an interactive run asks which side to keep. A non-interactive run exits successfully and leaves the remote untouched.link is for branches managed by another tool, such as Jujutsu. It pushes the named branches, creates any missing pull requests, and updates the stack on GitHub without writing .git/gh-stack. A stack number as the first argument appends the rest to that stack.merge merges every open pull request from the bottom through the one you choose, as one operation. A merge queue on the base branch receives the stack instead, and the queue picks the merge method.

-b, --base branch

init, link: trunk branch for the bottom of the stack. Defaults to the repository default branch. link ignores this when appending to an existing stack.

add: stage all changes, including untracked files. Requires -m. Mutually exclusive with -u.

add: stage changes to tracked files only. Requires -m. Mutually exclusive with -A.

add: commit with this message before creating the branch. With no branch name, the name is generated from the date and the message.

submit: skip the editor and use generated pull request titles. New pull requests are drafts unless --open is also set.

submit, link: mark new and existing pull requests as ready for review.

submit, sync, rebase, push, link: remote to use. Defaults to the detected remote.

sync: delete local branches whose pull requests have merged.

rebase: only rebase from the trunk through the current branch.

rebase: only rebase from the current branch through the top.

rebase: rebase stack branches onto each other, without fetching or rebasing onto the trunk.

rebase, modify: resume after conflicts are resolved and staged.

rebase, modify: restore the stack to the state before the operation.

rebase: set the committer date to the author date. Alias: --preserve-dates.

view: one line per branch.

view: print the stack as JSON.

merge: merge, squash, or rebase. Shorthands: --merge, --squash, --rebase.

merge: merge without prompting, using the last-used method unless one is given.

unstack: drop local tracking and leave the stack on GitHub.

alias: remove a previously created alias.

GH_STACK_THEME selects the color palette for submit, modify, view, and other colored output. Values are auto (default; follow the terminal background), light, and dark.GH_STACK_HYPERLINKS forces OSC 8 links in gh stack view --short. Set it to 1 or 0 when terminal detection is wrong. Unsupported terminals print the full URL.

init [branches...]

Start a new stack. Existing branches are adopted; missing ones are created.

Add a branch on top of the current stack and check it out. Run it from the top branch.

Show branches, order, pull request links, and the latest commit.

Check out a stack by stack number, pull request number or URL, or branch name.

Open a terminal UI to drop, fold, insert, rename, or reorder branches.

Remove local tracking and unstack the pull requests on GitHub. Also available as delete.

Push every branch, then create or update pull requests and the stack on GitHub.

Fetch, rebase, push, and refresh pull request state. Opening pull requests stays with submit.

Pull from the remote and rebase the stack from the trunk upward.

Push active branches with a per-branch --force-with-lease. Pull requests stay with submit.

Create or update a stack on GitHub from branch names or pull requests, without local tracking.

Merge every pull request up through the chosen one. If any cannot merge, none do.

Pick another branch in the current stack.

Move n branches toward the top, away from the trunk (default 1).

Move n branches toward the trunk (default 1).

Check out the branch furthest from the trunk.

Check out the branch closest to the trunk.

Check out the trunk branch, such as main.

Install a wrapper in ~/.local/bin/ (default name gs) that forwards to gh stack.

Open a GitHub Discussion in the gh-stack repository.

Stacked pull requests are in public preview, so the command set can change. The repository must have stacked pull requests enabled; otherwise commands fail with exit code 9.submit (without --auto), modify, switch, and checkout with no argument open a full-screen interface and need a terminal. modify also requires a clean work tree, a linear history, and no rebase or merge queue in progress.push updates each branch with --force-with-lease. The push is not atomic: some branches can update while another is rejected.This page documents github/gh-stack, invoked as gh stack. Other projects publish different tools under the same extension name.

GitHub published the gh-stack extension in 2026 (the github/gh-stack repository was created in February 2026). Stacked pull requests in GitHub CLI are a public preview.

gh(1), gh-pr(1), git(1), git-rebase(1), git-branchless(1), jj(1)

Source code · Homepage · Documentation