GitHub Stack Manager for VS Code

GitHub Stack Manager is a native VS Code interface for the official github/gh-stack GitHub CLI extension. The upstream CLI owns stack metadata, rebases, pushes, pull requests, GitHub Stack linking, synchronization, and merges; this extension adds an Activity Bar tree, command palette actions, status, confirmations, and conflict recovery.

Important

GitHub Stacked PRs is currently in private preview. The CLI and GitHub Stack operations require the feature to be enabled for your repository. See the official gh-stack repository for current availability.

Architecture

This extension deliberately does not implement a second stack format.

VS Code commands and tree
          ↓
  gh stack CLI commands
          ↓
.git/gh-stack + Git + GitHub Stacks API

• Stack state is read from gh stack view --json.
• New stacks use gh stack init.
• New layers use gh stack add.
• Navigation and checkout use gh stack up, down, and checkout.
• Push, submit, rebase, sync, merge, and local unstacking delegate directly to their matching gh stack commands.
• Interrupted rebases recover through gh stack rebase --continue or --abort.
• The extension never reads or writes .git/gh-stack itself.

Requirements

1. VS Code 1.96 or newer.
2. Git and GitHub CLI (gh) available on PATH.
3. An authenticated GitHub CLI session (gh auth login).
4. The official extension installed with gh extension install github/gh-stack.
5. Access to the GitHub Stacked PRs private preview for the target repository.

If gh stack is missing, the Activity Bar offers an explicit install action. Installation is never performed silently.

Features

• Visualizes the active official stack from trunk to top, including current branch, PR number, open/queued/merged state, and rebase warnings.
• Initializes existing branches and adds new branches at the top of a stack.
• Checks out a local or remote stack by stack number, PR number, PR URL, or branch.
• Pushes or submits the whole stack with non-interactive upstream commands.
• Rebases or synchronizes the stack, with optional pruning of merged local branches.
• Opens PRs, marks draft PRs ready, copies a linked Markdown summary, and atomically merges the active stack.
• Opens the upstream gh stack modify TUI in an integrated terminal for reordering, folding, inserting, renaming, or dropping layers.
• Exposes upstream rebase Continue and Abort recovery actions.

Start a stack

1. Check out an existing feature branch.
2. Run GitHub Stack: Initialize Current Branch and choose the trunk branch.
3. Commit that layer.
4. Run GitHub Stack: Create Branch on Top and commit the next layer.
5. Choose Submit Stack.

Equivalent CLI operations:

gh stack init --base main feature/api
gh stack add feature/ui
gh stack submit --auto --remote origin

New PRs are drafts by default. Disable ghStack.draftByDefault to pass --open during submission.

Commands

VS Code command	Official operation
Initialize Current Branch	gh stack init --base <trunk> <branch>
Create Branch on Top	gh stack add <branch>
Check Out Stack or Pull Request	gh stack checkout <reference>
Push Stack	gh stack push --remote <remote>
Submit Stack	gh stack submit --auto --remote <remote>
Restack	gh stack rebase [branch] --remote <remote>
Sync with Base	gh stack sync --remote <remote> [--prune]
Merge Current Stack	gh stack merge --yes --merge-method <method>
Remove Local Stack Tracking	gh stack unstack --local
Continue / Abort Rebase	gh stack rebase --continue / --abort

Cmd+Alt+Up/Down on macOS and Ctrl+Alt+Up/Down elsewhere invoke gh stack up/down.

Settings

Setting	Default	Purpose
ghStack.remote	origin	Remote passed to upstream commands
ghStack.draftByDefault	true	Omit --open when submitting
ghStack.mergeMethod	squash	Method passed to gh stack merge
ghStack.pruneOnSync	false	Pass --prune to gh stack sync
ghStack.autoRefresh	true	Refresh when VS Code regains focus

Install the VSIX

code --install-extension gh-stack-manager-0.2.0.vsix

Or choose Extensions: Install from VSIX… in VS Code.

Build and verify

npm ci
npm run check
npm test
npm run package

The final command creates a tested .vsix. Marketplace publishing additionally requires replacing the placeholder publisher in package.json with a publisher account you control.

Safety

• Every mutating action starts with an explicit user command.
• Installing or upgrading github/gh-stack is explicit.
• Rebase, sync, merge, and local unstack actions require confirmation where data or history can change materially.
• Submission is always non-interactive (--auto), avoiding hidden terminal prompts.
• The official CLI remains the single source of truth for leases, rebase state, metadata locking, and GitHub API behavior.

License

MIT