v0.0.7

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.

gh-stack is a GitHub CLI extension for managing stacked branches and pull requests. Learn more about GitHub Stacked PRs here.

View the Quick Start guide or upgrade to the latest version with:

gh extension upgrade stack

What's new in v0.0.7

Added

• Interactive gh stack submit TUI: submit now opens a single-screen, keyboard- and mouse-driven interface for customizing a whole stack before anything is created. A left-hand git-graph timeline shows each branch's PR state and lets you toggle which branches become PRs (with dependency cascade); a right-hand editor lets you set each PR's title, description (with live markdown preview and $EDITOR support), and ready/draft state. Previously submit could only customize each PR's title.
• Smaller, more responsive TUI header: The shared header used by view, modify, and the new submit TUI takes up less screen space and has a more responsive layout. It will optionally display a GitHub logo image when the terminal supports it.
• Light and dark terminal theming: A new background-aware color palette adapts both the interactive TUIs and plain command output (status messages, prompts) to light, dark, and solarized terminals instead of assuming a dark background. Set GH_STACK_THEME=auto|light|dark to force the palette on terminals that mis-detect their background.

Changed

• gh stack submit adopts existing remote stacks: When a stack already exists on GitHub but isn't tracked locally (e.g. created from the web UI or another clone), submit now reconciles against the remote stack — adopting and updating it — instead of failing with "Pull requests are already part of a stack." It refuses and warns (rather than silently dropping PRs) when the remote stack contains PRs you don't track locally, or when PRs span multiple stacks.
• gh stack submit forks onto a new stack when the base is fully merged: Once every PR in a tracked stack has merged, submitting new branches on top now starts a fresh stack rooted at the trunk instead of failing with the "each PR's base ref must be the previous PR's head ref" error. Normal partial, bottom-up merges are left untouched.
• gh stack sync reconciles the remote stack object: sync now creates, adopts, or updates the stack on GitHub when two or more open PRs exist (it never opens PRs — that's still submit's job), and reports Stack synced only when the remote stack object actually reflects the local stack, otherwise Branches synced.
• gh stack unstack preflight eligibility check: unstack now verifies that at least one associated PR is eligible before deleting, refusing up front when all PRs are ineligible (merged, queued for merge, or auto-merge enabled).
• Fully merged stacks reflect "nothing actionable" in the TUIs: gh stack view hides the cursor and dims the cursor-dependent shortcuts when every branch is merged, and gh stack modify now exits early with a message pointing to gh stack init instead of opening an empty editor.

Fixed

• Misleading gh stack sync success message: sync no longer prints ✓ Stack synced when it never actually created or updated a stack object on GitHub.
• Confusing gh stack unstack API errors: Failed deletions now surface clearer messages for specific GitHub API responses (such as HTTP 422) instead of a raw error.

Changelog

• Bump js-yaml from 4.1.1 to 4.2.0 in /docs in the npm_and_yarn group across 1 directory by @dependabot[bot] in #130
• Add AGENTS.md and copilot-instructions.md for AI agent onboarding by @francisfuzz in #133
• Unstack Updates: preflight PR eligibility before delete and improve API errors by @wiseemily88 in #136
• Redesign TUI shared header and embed the GitHub logo as an image by @skarim in #143
• Add an interactive submit TUI for customizing each PR's title, description, and draft state by @skarim in #147
• Adapt theme colors to light and dark terminals by @skarim in #149
• Adopt existing remote stacks on submit by @skarim in #153
• Fork unmerged branches into new stack by @skarim in #154
• Create/update stack on remote during sync by @skarim in #156

Full Diff: v0.0.6...v0.0.7

v0.0.6

What's new in v0.0.6

Added

• gh stack rebase --no-trunk: New flag that runs only the inter-branch cascade rebase, skipping all remote fetch and trunk operations so you can align branches without touching the network.
• PR URL arguments: gh stack link and gh stack checkout now accept full PR URLs (e.g. https://github.com/org/repo/pull/42) in addition to PR numbers and branch names.
• Cached remote selection: After interactively choosing a remote, you can save it to gh-stack.remote git config so you're not prompted on every operation.
• PAT auth warning: When authenticated with an unsupported personal access token, the CLI now shows a clear "run gh auth login" message instead of a misleading "Stacked PRs are not enabled" error.

Changed

• gh stack link PR eligibility validation: Merged, closed, merge-queued, or auto-merge-enabled PRs are now rejected up front with per-PR error messages before any stack operations run.
• Auto-merge disabled on adopted PRs: gh stack submit now detects and disables auto-merge on existing PRs it adopts, preventing them from merging independently and breaking the stack.
• gh stack init no longer silently detects prefixes: Explicit branch names with slashes are taken literally; use --prefix to opt into a prefix.

Fixed

• git push failures with stale tracking refs: Push now fetches and builds explicit --force-with-lease leases per branch, fixing "stale info" rejections for branches lacking a local tracking ref.
• gh stack sync with no local trunk: Sync now skips the trunk fast-forward silently when only the remote tracking ref exists, avoiding spurious rebases and force-pushes.
• Missing local trunk crashes: A new ensureLocalTrunk helper fetches and creates the trunk branch for modify, rebase, and trunk when it only exists on the remote (e.g. after renaming the initial branch).

Changelog

• Bump github.com/cli/cli/v2 from 2.92.0 to 2.93.0 in the go_modules group across 1 directory by @dependabot[bot] in #110
• link PR validation by @skarim in #112
• alert for unsupported auth tokens by @skarim in #113
• disable automerge when adding existing PRs to stack by @skarim in #120
• parse PR URLs in args by @skarim in #122
• fix push for branches with stale tracking refs by @skarim in #124
• fix for sync with no local trunk by @skarim in #125
• remove silent prefix detection in init by @skarim in #126
• ensure local trunk branch for required operations by @skarim in #127
• cache selected remote by @skarim in #128
• rebase without trunk by @skarim in #129

Full Diff: v0.0.5...v0.0.6

v0.0.5

What's new in v0.0.5

Added

• Insert branches with gh stack modify: New i / I keybindings in the modify TUI to insert empty branches below or above the cursor, applied alongside other structural changes.
• gh stack add adopts existing branches: If the target branch already exists locally and isn't part of another stack, add adopts it instead of erroring.
• gh stack trunk: New navigation command that checks out the trunk branch of the current stack.
• gh stack rebase --committer-date-is-author-date: New opt-in flag (alias --preserve-dates) keeps committer dates equal to author dates so identical content rebased onto an identical parent produces stable SHAs.
• Inline prefix prefill in prompts: Branch name prompts in init/add now place the configured prefix directly in the editable input (with cyan-colored user text) instead of silently prepending it.

Changed

• gh stack modify smart checkout: After modify, the CLI now switches to the nearest surviving branch (rename target, fold target, neighbor, or stack top) instead of staying on the original branch, which may no longer be part of a stack.
• gh stack modify only requires submit when PRs are affected: Modify only transitions to the pending-submit phase when changes touch branches with open PRs; purely local restructuring is applied immediately and does not trigger the prompt to submit.
• Bump github.com/cli/cli/v2 from 2.86.0 to 2.92.0.

Fixed

• gh stack sync skipping rebase after a local git pull: Sync now runs the cascade rebase whenever stack branches are stale relative to trunk, not only when trunk or branches were fast-forwarded in the current run.

Changelog

• Bump github.com/cli/cli/v2 from 2.86.0 to 2.92.0 in the go_modules group across 1 directory by @dependabot[bot] in #103
• fix for rebase in sync cmd by @skarim in #95
• rebase with preserve dates opt by @skarim in #96
• input prompter improvements by @skarim in #98
• update add cmd to adopt existing branches by @skarim in #101
• swtich to nearest surviving branch after modify by @skarim in #105
• modify: only require submit when changes affect PRs by @skarim in #106
• insert branches with modify by @skarim in #107
• trunk command by @skarim in #108

Full Diff: v0.0.4...v0.0.5

v0.0.4

What's new in v0.0.4

Added

• gh stack sync --prune: New flag (and interactive prompt) to delete local branches and remote-tracking refs for merged PRs during sync.
• gh stack init multi-branch support: Pass multiple branch names as arguments to init; existing branches are adopted automatically without any extra flag.
• Contextual post-command hints: After add, push, submit, and checkout, the CLI now prints "what to do next" suggestions to guide users through the workflow.
• Rebase workflow docs: New comprehensive "Rebasing Your Stack" section in the workflows guide covering cascading rebase, conflict resolution, and CLI vs. web UI differences.
• Grouped root help: Root gh stack --help now organizes commands into categories (Core, Stack Management, Navigation, Other) with a "Learn More" footer linking to docs and feedback.

Changed

• gh stack merge removed: The command was a placeholder that opened the browser rather than performing a real merge; it will be re-added once the merge API for Stacked PRs is available.
• gh stack init prefix detection: The --adopt flag is deprecated (hidden but still accepted); branch prefix is now auto-derived from branch names (e.g. feat/a feat/b → prefix feat) instead of prompting upfront.
• TUI merged-branch guards: Merged branches can no longer be selected via keyboard, mouse click, or Enter in the stack view or modify TUI; the cursor skips over them automatically.
• Improved CLI help text: All commands now have Long descriptions and Example blocks with real-world, commented usage for better discoverability.

Fixed

• gh stack submit on partially-merged stacks: Merged PRs are now included in the API payload, preventing "Stack contents have changed" rejections when some branches in a stack have already been merged.

Changelog

• Bump astro from 6.1.8 to 6.3.1 in /docs in the npm_and_yarn group across 1 directory by @dependabot[bot] in #86
• Bump devalue from 5.6.4 to 5.8.1 in /docs in the npm_and_yarn group across 1 directory by @dependabot[bot] in #90
• commands help text by @skarim in #88
• remove merge command by @skarim in #89
• support multiple branches during init by @skarim in #91
• docs on rebase workflow by @skarim in #93
• prune merged branches by @skarim in #94

Full Diff: v0.0.3...v0.0.4

v0.0.3

What's new in v0.0.3

Added

• gh stack modify: New interactive TUI command to restructure a stack — drop, fold, rename, and reorder branches — applied atomically with cascading rebases and conflict recovery (--continue / --abort).
• gh stack submit --open: New --open flag to create PRs as ready for review; PRs are now created as drafts by default, with --open also converting existing drafts to ready for review.
• PR template support: gh stack submit and gh stack link now automatically detect and use the repository's pull request template as the PR body.
• gh stack view --json agent improvements: When --json is set and the stack is ambiguous, the command now returns a proper exit code instead of launching an interactive prompt.

Changed

• gh stack unstack simplified: The optional [branch] argument is removed; the command always targets the active (currently checked-out) stack.
• TUI load performance: API calls in sync and git operations in LoadBranchNodes are now parallelized; a "Loading stack..." indicator is shown while data is fetched.
• Reduced GraphQL footprint: Removed ~15 unused fields across 5 queries and deleted one dead query, reducing API rate limit consumption.
• Docs corrections: FAQ answers updated to reflect atomic landing behavior, merge queue grouping, and gh stack modify as the primary stack restructuring tool.

Fixed

• git push --force-with-lease failures on shallow clones: A targeted git fetch of active branches now runs before every push, ensuring remote tracking refs are up to date.
• GraphQL int32 overflow: PR numbers are now validated before conversion to graphql.Int, preventing silent truncation on very large PR numbers.

Changelog

• Bump astro from 6.0.8 to 6.1.8 in /docs in the npm_and_yarn group across 1 directory by @dependabot[bot] in #60
• Guard GraphQL PR number conversion against int32 overflow by @Copilot in #56
• docs: stack object in pull_request webhooks by @Copilot in #67
• modify command by @skarim in #72
• Bump postcss from 8.5.8 to 8.5.14 in /docs in the npm_and_yarn group across 1 directory by @dependabot[bot] in #73
• docs content updates by @skarim in #83
• simplify unstack to only target the active stack by @skarim in #74
• run fetch before push operations by @skarim in #75
• open PRs as draft by default by @skarim in #76
• use PR template when opening PRs by @skarim in #77
• trim GraphQL queries by @skarim in #78
• optimize TUI load times by @skarim in #79
• improve agent friendliness of view --json by @skarim in #80

Full Diff: v0.0.2...v0.0.3

v0.0.2

What's new in v0.0.2

Added

• gh stack link: New API-only command to create and link a stack on GitHub from branch names or PR numbers — ideal for users managing branches with external tools like jj, Sapling, or ghstack.
• gh stack switch: New interactive picker command to switch to any branch in the current stack, displayed in order with position numbers.
• Stacked PR preflight check: gh stack submit now verifies stacked PR availability before pushing branches, prompting to create regular PRs instead if stacks aren't enabled for the repository.

Changed

• gh stack sync and gh stack rebase fast-forward: Stack branches where local is strictly behind remote are now fast-forwarded before the cascade rebase, preventing upstream commits from being dropped.

Fixed

• gh stack checkout on partially-merged stacks: Merged branches are now skipped when checking out a remote stack; a message is shown if the stack is fully merged.
• Inflated diff counts in gh stack view: git merge-base is now always used to find the fork point for diff computation, preventing inflated file counts when the base branch has advanced since stack init.
• gh stack rebase crash on deleted branches: Merged branches that no longer exist locally are filtered out before resolving refs, preventing a rev-parse failure during the cascade rebase.
• gh stack sync crash on deleted branches: Same fix applied to the sync code path — deleted merged branches are skipped when building the ref snapshot.
• --onto rebase failures after partial merges: Fixed three edge cases where git rebase --onto would fail or replay already-applied commits after branches in the stack had been merged.
• Stale merged/closed PRs adopted for reused branch names: gh stack submit and gh stack view no longer pick up old merged or closed PRs when a branch name is reused in a new stack.

Changelog

• skip pulling merged branches during remote checkout by @skarim in #16
• docs site styling by @skarim in #20
• docs site content updates by @skarim in #28
• fix for inflated diff counts when base branch has been updated since stack init by @skarim in #39
• fast forward active branches where local is behind remote by @skarim in #40
• fix for rev-parse error when rebasing over deleted branches by @skarim in #41
• fix for rev-parse error during sync with deleted branches by @skarim in #42
• fix --onto rebase for merged branches by @skarim in #43
• minor docs styling & content updates by @skarim in #48
• preflight check for stacked PR availability in submit by @skarim in #44
• ignore stale merged/closed PRs for reused branch names by @skarim in #49
• link command for api-only operations by @skarim in #50
• switch command by @skarim in #51

Full Diff: v0.0.1...v0.0.2

v0.0.1

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.

gh-stack is a GitHub CLI extension for managing stacked branches and pull requests. Learn more about GitHub Stacked PRs here.

Quick Start

Make sure you have the gh CLI installed first, then run:

gh extension install github/gh-stack

You can optionally set up an alias to use gs instead of gh stack:

gh stack alias

Navigate to your repo and start stacking:

# Start a new stack from your default branch
gs init 
# ... make changes, stash, and commit using git

# Add a new branch to the stack
gs add next-branch
# ... make changes, stash, and commit using git

# Push all branches
gs push

# Open a stack of PRs
gs submit

Full details of the CLI and available commands here.

Use with Agents

Teach agents how to use the CLI by installing the included skill:

npx skills add github/gh-stack

Upgrading

If you already have the extension installed, upgrade to the latest release with:

gh extension upgrade stack

---

Full Changelog: https://github.com/github/gh-stack/commits/v0.0.1