--- schema_version: 1 route: /t/gh-stack.md tool: "gh-stack" --- # sincecutoff.com /t/gh-stack — gh-stack - name: gh-stack - kind: cli - parent: gh - children: none - homepage: Changes to the tools coding agents drive, since a model's training cutoff, each linked to its first-party source. Check installed versions and limitations before acting; a cutoff date does not establish what a model knows. Original editorial content: [Apache 2.0](https://sincecutoff.com/v1/data-license.txt), by [0xPatrick](https://0xpatrick.dev). Preserve applicable license and [NOTICE](https://sincecutoff.com/notice.txt) attribution when redistributing. Third-party source text and examples retain their own rights. [License scope and attribution](https://sincecutoff.com/v1/license.json). To stay current, read the changes feed: [`/v1/changes.md?tool=gh-stack`](https://sincecutoff.com/v1/changes.md?tool=gh-stack) (or `.json`), adding `since=YYYY-MM-DD` for your training cutoff. Entries for registered children are included; the registry itself is `/v1/tools.json`. How to page and save your place: [llms.txt](https://sincecutoff.com/llms.txt). ### gh-stack rebase, sync, and modify operate across worktrees (2026-10-02) - slug: gh-stack-rebase-sync-and-modify-operate-across-worktrees-14e6b34579ad - score: 0.98 How to use it: When a stack’s branches are spread across worktrees, use `gh stack rebase`, `gh stack sync`, or `gh stack modify`; gh-stack runs each change in the worktree owning its branch. If a rebase or modify pauses for conflicts, resolve and stage them in the reported checkout, then continue or abort from any worktree. Examples: ``` gh stack rebase ``` ``` gh stack sync ``` ``` gh stack modify ``` - why_it_matters: Rebase, synchronize, or modify a stack whose branches are checked out in different worktrees. - before: Gather the whole stack into one directory before running these commands. - sources: , - gotchas: "Version: v0.2.0"; "Requires gh extension install github/gh-stack"; "gh stack rebase --continue: Continue the rebase after resolving conflicts; stage resolutions with `git add` first."; "gh stack rebase --abort: Abort the rebase and restore branches to their pre-rebase state."; "gh stack modify --continue: Continue modify after resolving conflicts."; "gh stack modify --abort: Abort modify and restore the stack to its pre-modify state."; "Prerequisite: Git 2.36+ and GitHub CLI (`gh`) v2.0+ are required."; "Prerequisite: Install the extension with `gh extension install github/gh-stack`."; "Prerequisite: `modify` requires an active local stack, a clean working tree, no rebase in progress, no queued PR, and linear commit history."; "Requires Git 2.36+."; "gh-stack never creates, removes, or auto-stashes worktrees." ### gh stack add offers to initialize a stack (2026-09-02) - slug: gh-stack-add-offers-to-initialize-a-stack-bee1403f6bf5 - score: 0.94 How to use it: When `gh stack add` runs interactively on a branch outside a stack, accept its offer to initialize a stack; the supplied or generated branch name becomes the first layer. Examples: ``` gh stack add [branch] ``` - why_it_matters: Add the current branch as the first layer when working from a branch that is not part of a stack. - before: Previously, running `add` from a branch outside a stack failed. - sources: , , - gotchas: "Version: v0.1.1"; "branch (optional positional argument): Branch name; when initializing from a non-stack branch, the supplied or auto-generated name becomes the first layer."; "Prerequisite: The documented initialization offer is interactive."; "Prerequisite: Install the extension with `gh extension install github/gh-stack`. Requires GitHub CLI 2.0+ and Git 2.36+; authenticate with `gh auth login` if needed." ### gh stack checkout resolves active remote stacks (2026-09-02) - slug: gh-stack-checkout-resolves-active-remote-stacks-039ba6fea416 - score: 0.96 How to use it: If the current branch or requested branch is not tracked locally but belongs to an active remote stack, run `gh stack checkout` or `gh stack checkout ` and accept the prompt to check it out. The command imports the matching stack through the PR checkout flow; fully merged stacks are omitted. ([v0.1.1 release](https://github.com/github/gh-stack/releases/tag/v0.1.1)) Examples: ``` gh stack checkout ``` ``` gh stack checkout ``` - why_it_matters: Check out a stack when the current branch or a requested branch belongs to an active GitHub stack but is not in a local stack or tracked locally. - before: For a branch not tracked locally or not part of a local stack, use the existing checkout behavior if remote resolution does not offer a match. - sources: , - gotchas: "Version: v0.1.1"; "[]: Optional branch name to check out; when supplied and not tracked locally, the command searches remote stacks for a match. With no argument, it checks whether the current branch belongs to an active remote stack. ([gh-stack README](https://github.com/github/gh-stack/blob/v0.1.1/README.md))"; "Prerequisite: Install the GitHub CLI extension with `gh extension install github/gh-stack`. ([v0.1.1 release](https://github.com/github/gh-stack/releases/tag/v0.1.1))"; "Prerequisite: The command’s no-argument remote detection is offered in an interactive terminal. ([gh-stack README](https://github.com/github/gh-stack/blob/v0.1.1/README.md))"; "Resolution is best-effort: network failures, no or multiple matches, or a declined prompt fall through to existing behavior."; "Fully merged stacks are ignored." ### gh-stack adds atomic stack merging with gh stack merge (2026-07-29) - slug: gh-stack-adds-atomic-stack-merging-with-gh-stack-merge-0647b724a4c1 - score: 0.95 How to use it: If merging the current stack or a selected stack or PR, run `gh stack merge` with the appropriate optional target. Choose the merge extent and method interactively, or use `--yes` or a non-interactive terminal with a method flag to merge without prompts; the operation is all-or-nothing. Examples: ``` gh stack merge ``` ``` gh stack merge --yes --squash ``` ``` gh stack merge --yes --merge-method rebase ``` - why_it_matters: Merge the current stack or a selected stack or pull request into its base branch. - sources: , - gotchas: "Version: v0.1.0"; "[]: Selects a stack to merge even when it is not checked out; omitting the target uses the active local stack."; "[]: Selects a PR and merges every PR in its stack up to and including it."; "--yes / -y: Merge without prompting for confirmation; non-interactive terminals also run without prompting."; "--merge-method : Sets the method to `merge`, `squash`, or `rebase`."; "--merge: Shorthand for the `merge` method."; "--squash: Shorthand for the `squash` method."; "--rebase: Shorthand for the `rebase` method."; "Prerequisite: Install with `gh extension install github/gh-stack`. Requires GitHub CLI (`gh`) 2.0 or later and Git 2.36 or later. Authenticate with `gh auth login` if not already authenticated."; "Prerequisite: Each PR must be open and not a draft. GitHub evaluates branch protection and repository rules during the merge."; "Interactive wizard is for terminal use."; "The wizard offers only merge methods allowed by the repository and defaults to the last-used method." ### gh-stack branch names no longer use stack prefixes or numbered naming (2026-07-15) - slug: gh-stack-branch-names-no-longer-use-stack-prefixes-or-numbered-naming-98eee258a6ae - score: 0.94 How to use it: When adding a named branch, use its name directly; `gh stack add refactor/foo` creates that branch. To create a branch from a message, run `gh stack add -m ""`; the v0.0.8 release says an omitted name generates `MM-DD-slug`. Examples: ``` gh stack add refactor/foo ``` ``` gh stack add -m "" ``` - why_it_matters: When adding a branch with a chosen name or generating one from a message, use the branch name directly or the new generated-name form. - before: Use the stack branch-name prefix or coupled numbered naming; `init` accepts `-p/--prefix` and `-n/--numbered`. - sources: , - gotchas: "Version: v0.0.8"; "branch: Optional branch name; if omitted, `add` prompts for one, or auto-generates one when `-m` is provided."; "-m, --message : Create a commit with this message before creating the branch; with no branch name, generates the branch name."; "-A, --all: Stage all changes, including untracked files; requires `-m`."; "-u, --update: Stage changes to tracked files only; requires `-m`."; "Prerequisite: Install the extension with `gh extension install github/gh-stack`; requires GitHub CLI (`gh`) v2.0 or later."; "Prerequisite: For an existing stack, run `add` while on its topmost branch."; "Existing stack files carrying `prefix`/`numbered` keys still load; the fields are ignored and dropped on the next save."; "Docs conflict: The current README is newer than v0.0.8 and gives an auto-generated-name example `03-24-auth_middleware`; the release states the v0.0.8 form is `MM-DD-slug`."; "Docs conflict: The current README documents only `-b, --base ` for `init` and omits the removed `-p/--prefix` and `-n/--numbered` flags; it does not document legacy `prefix`/`numbered` file handling." ### gh stack checkout opens an interactive stack picker (2026-07-15) - slug: gh-stack-checkout-opens-an-interactive-stack-picker-76fc5f8b58f0 - score: 0.96 How to use it: When you need to choose a stack without knowing its identifier, run `gh stack checkout` in an interactive terminal and select it from the picker. Use the All/Local/Remote tabs or `/` search; selecting a remote-only stack clones it locally before switching to it. Examples: ``` gh stack checkout ``` - why_it_matters: When choosing a local or GitHub stack without already knowing its identifier, run `gh stack checkout` with no argument and select the desired stack. - sources: , - gotchas: "Version: v0.0.8"; "stack-number, pr-number, pr-url, branch: Optional checkout target; omitting it opens the picker in an interactive terminal."; "All / Local / Remote tabs: Filter the picker by all available stacks, locally tracked stacks, or remote stacks."; "/: Start searching the picker; the v0.0.8 release says search matches the stack number, base, and every stack branch, including mid-stack branches."; "Prerequisite: The picker opens when run without arguments in an interactive terminal."; "Prerequisite: Install the extension with `gh extension install github/gh-stack`; requires GitHub CLI `gh` v2.0+. Stacked PRs must be enabled for the repository."; "The picker searches stack number, base branch, and every branch in the stack, including mid-stack branches." ### gh-stack commands reference stacks by number (2026-07-15) - slug: gh-stack-commands-reference-stacks-by-number-a284b3dc9565 - score: 0.92 How to use it: When checking out or unstacking a tracked stack by its GitHub UI number, use that number: run `gh stack checkout ` to check it out or `gh stack unstack ` to unstack it. Find the number in the GitHub UI or gh-stack output. Examples: ``` gh stack checkout ``` ``` gh stack unstack ``` - why_it_matters: When checking out or unstacking a tracked stack by its GitHub stack UI identifier, use its stack number. - sources: , - gotchas: "Version: v0.0.8"; " (checkout): A stack number; checkout also accepts a PR number, PR URL, or branch. A bare number is matched as a stack or PR number before being tried as a branch name."; " (unstack): The GitHub UI stack number; targets that stack from anywhere in the repository. If omitted, targets the active stack."; "Prerequisite: Install the extension with `gh extension install github/gh-stack`; requires GitHub CLI (`gh`) v2.0+."; "Prerequisite: Stacked PRs must be enabled for the repository. Authenticate with GitHub CLI to run stack operations." ### gh stack link appends pull requests to an existing stack (2026-07-15) - slug: gh-stack-link-appends-pull-requests-to-an-existing-stack-ccd877353da0 - score: 0.96 How to use it: When appending pull requests to an existing stack, run `gh stack link `; the stack number selects the target, and the remaining arguments are ordered bottom to top. Examples: ``` gh stack link 7 48 ui-polish ``` - why_it_matters: When adding pull requests to the top of an existing stack, link them by stack number without restating the stack's existing pull requests. - before: Restate every PR already in the stack along with the PRs to append. - sources: , - gotchas: "Version: v0.0.8"; " (required): Target existing stack number; the task’s release example uses it as the first argument."; " (required): One or more branch names, PR numbers, or PR URLs, in stack order from bottom to top. Branches are pushed automatically; mismatched PR base branches are corrected."; "Prerequisite: Install GitHub CLI 2.0+ and Git 2.36+; install the extension with `gh extension install github/gh-stack`. Authenticate with `gh auth login` if needed."; "The operation appends PRs to the top of an existing stack."; "PRs that belong to a different stack are rejected." ### gh stack unstack dissolves a remote stack by number (2026-07-15) - slug: gh-stack-unstack-dissolves-a-remote-stack-by-number-4c892239ce17 - score: 0.94 How to use it: When dissolving a stack that may not be tracked locally, run `gh stack unstack ` from within the repository. It dissolves the stack through GitHub’s API and removes local tracking when present. Examples: ``` gh stack unstack ``` - why_it_matters: When dissolving a stack that may not be tracked locally, unstack it by its stack number from within the repository. - sources: , - gotchas: "Version: v0.0.8"; " (required): Stack number shown in the GitHub stack UI; targets that stack for unstacking."; "Prerequisite: Install the extension with `gh extension install github/gh-stack`; requires GitHub CLI (`gh`) v2.0 or later."; "Prerequisite: The Stacked PRs feature must be enabled for the repository; authenticate with GitHub CLI to run stack operations."; "The command works from anywhere in the repository, whether or not the stack is tracked locally." ### gh stack submit TUI customizes a whole stack (2026-06-30) - slug: gh-stack-submit-tui-customizes-a-whole-stack-e5fc2aba50b3 - score: 0.96 How to use it: When preparing PRs for a stack, run `gh stack submit` in an interactive terminal to choose branches, edit each PR’s title and description, and set ready or draft state. Submit the choices together with Ctrl+S. Examples: ``` gh stack submit ``` - why_it_matters: Before creating PRs for a stack, customize which branches become PRs and each PR’s details. - before: Previously, submit could only customize each PR’s title. - sources: , - gotchas: "Version: v0.0.7"; "branch selection (Ctrl+X): Deselect a branch; deselecting it also deselects branches above it. Re-including a branch re-includes branches below it. Branches without PRs are included by default."; "PR title: Edit each PR’s title in the editor."; "PR description: Edit each PR’s description; the editor provides markdown preview and a `$EDITOR` escape."; "ready/draft toggle: Choose ready for review or draft for each PR. New PRs default to ready for review in the editor."; "Ctrl+S (required): Submit the edited PRs together."; "Prerequisite: Install the extension with `gh extension install github/gh-stack`; requires GitHub CLI (`gh`) v2.0+."; "Prerequisite: Stacked PRs is in private preview; the feature must be enabled for the repository."; "Prerequisite: Run in an interactive terminal to open the editor."; "The interface is keyboard- and mouse-driven." ### gh stack rebase adds --no-trunk (2026-06-15) - slug: gh-stack-rebase-adds-no-trunk-0fb30cb2dc67 - score: 0.94 How to use it: When you need to align stack branches without fetching or rebasing trunk, run `gh stack rebase --no-trunk`. Examples: ``` gh stack rebase --no-trunk ``` - why_it_matters: Rebase the branches in a stack without network access. - sources: , - gotchas: "Version: v0.0.6"; "--no-trunk: Skip trunk; rebase stack branches onto each other with no fetch or trunk rebase."; "Runs only the inter-branch cascade rebase; skips all remote fetch and trunk operations." ### gh stack modify inserts empty branches (2026-05-26) - slug: gh-stack-modify-inserts-empty-branches-f8ea69991bea - score: 0.94 How to use it: When restructuring a stack, run `gh stack modify`; in its TUI press `i` to stage an empty branch below the cursor or `I` to stage one above, then press `Ctrl+S` to apply the staged changes. [v0.0.5 README](https://github.com/github/gh-stack/blob/v0.0.5/README.md#L388-L424) Examples: ``` gh stack modify ``` - why_it_matters: Insert an empty branch above or below a branch while restructuring a stack. - sources: , , , , , - gotchas: "Version: v0.0.5"; "i: Stage insertion of an empty branch below the cursor."; "I: Stage insertion of an empty branch above the cursor."; "Ctrl+S (required): Apply all staged changes."; "Prerequisite: Requires an active local stack, a clean working tree, no rebase in progress, no stack PR queued for merge, and linear commit history."; "Prerequisite: Requires GitHub CLI (`gh`) v2.0+ and installation of the extension with `gh extension install github/gh-stack`." ### gh-stack init adopts multiple branches and derives their prefix (2026-05-15) - slug: gh-stack-init-adopts-multiple-branches-and-derives-their-prefix-1450b30dea80 - score: 0.90 How to use it: When initializing a stack from multiple existing branches, run `gh stack init ...`; existing branches are adopted automatically and v0.0.4 derives the prefix from their names. Examples: ``` gh stack init ``` - why_it_matters: Initialize a stack from multiple existing branches with a shared prefix. - sources: , - gotchas: "Version: v0.0.4"; "branches... (required): One or more branch names, processed in order; existing branches are adopted automatically. For this task, supply multiple names."; "--adopt: Deprecated, hidden, but still accepted; existing branches no longer require it to be adopted."; "Prerequisite: Install the extension with `gh extension install github/gh-stack`; the README says GitHub CLI (`gh`) must be installed first."; "The `--adopt` flag is deprecated and hidden but still accepted."; "Docs conflict: Later official docs say automatic prefix detection was removed; branch names with slashes are taken literally. That behavior is newer than v0.0.4 and does not apply to this card's version: https://github.com/github/gh-stack/releases." ### gh-stack sync --prune deletes merged-PR refs during sync (2026-05-15) - slug: gh-stack-sync-prune-deletes-merged-pr-refs-during-sync-ec7e15ba10cc - score: 0.94 How to use it: When syncing a stack with merged PRs, run `gh stack sync --prune` to automatically delete their local branches. The documentation does not confirm deletion of remote-tracking refs. Examples: ``` gh stack sync --prune ``` - why_it_matters: During sync, remove local branches and remote-tracking refs for merged pull requests. - sources: , - gotchas: "Version: v0.0.4"; "--prune: Automatically delete local branches for merged PRs during sync."; "Prerequisite: Install the GitHub CLI extension with `gh extension install github/gh-stack`; the docs require GitHub CLI v2.0+ and Git 2.36+."; "Docs conflict: The release note says pruning deletes local branches and remote-tracking refs. The command documentation describes deletion of local branches only and does not confirm remote-tracking ref deletion." ### gh-stack gh stack modify restructures a branch stack (2026-05-11) - slug: gh-stack-gh-stack-modify-restructures-a-branch-stack-996d4c53c39b - score: 0.96 How to use it: When you have an active stack checked out, a clean working tree, no rebase in progress, no PR queued to merge, and linear history, run `gh stack modify` to open the TUI and stage branch changes. Save to apply them; if a conflict occurs, resolve it and run `gh stack modify --continue`, or restore the pre-modify state with `gh stack modify --abort`. Examples: ``` gh stack modify ``` ``` gh stack modify --continue ``` ``` gh stack modify --abort ``` - why_it_matters: Restructure a branch stack by dropping, folding, renaming, or reordering branches. - sources: , , - gotchas: "Version: v0.0.3"; "--continue: Continue after resolving conflicts."; "--abort: Abort the modify session and restore the stack to its pre-modify state."; "x: Drop a branch and its commits from the stack."; "d: Fold the selected branch into the branch below it, toward trunk."; "u: Fold the selected branch into the branch above it, away from trunk."; "r: Rename a branch locally and in stack metadata."; "Shift+↓ / Shift+↑: Move a branch down toward trunk or up away from trunk."; "Ctrl+S: Apply staged changes."; "Prerequisite: Requires an active stack checked out locally, a clean working tree, no rebase in progress, no PR in the stack queued for merge, and linear commit history."; "Prerequisite: Install GitHub CLI 2.0 or later and Git 2.36 or later; install the extension with `gh extension install github/gh-stack`. Authenticate with `gh auth login` if needed."; "Prerequisite: The release notes state Stacked PRs must be enabled for the repository for the CLI functionality to work."; "The command is interactive." ### gh stack switch interactively selects a branch in the current stack (2026-04-20) - slug: gh-stack-switch-interactively-selects-a-branch-in-the-current-stack-fad9d2f35cab - score: 0.96 How to use it: When you need to switch to a branch in the current stack, run `gh stack switch` in an interactive terminal and select the branch from the ordered picker. Examples: ``` gh stack switch ``` - why_it_matters: Interactively switch to a branch in the current stack. - sources: , , - gotchas: "Version: v0.0.2"; "Prerequisite: Requires an interactive terminal."; "Prerequisite: Install the extension with `gh extension install github/gh-stack`; requires GitHub CLI `gh` v2.0 or later."; "Interactive picker command."