CLI: ghs

Stack your PRs. Keep your Git.

A lightweight CLI for GitHub stacked pull requests. Create stacked branches, restack changes, and submit PRs with short commands built on GitHub Stack.

Installation Explore commands View on GitHub

Interactive demo · nothing executes

~/project

ghs add

Underlying command

gh stack add -- B2

Example: you are on untracked B2, created from stack tip A. ghs detects A, checks it out, then asks gh-stack to adopt B2. You finish back on B2.

The demonstration shows the commands ghs runs. Nothing executes in this demo.

Installation

Install once. Stack from your terminal.

Homebrew

version: 0.2.0
repository: https://github.com/peterlapin/ghs

Tap, then install

brew tap peterlapin/ghs https://github.com/peterlapin/ghs.git
brew install peterlapin/ghs/ghs

Use the explicit tap URL above and the full formula name to install ghs.

Run only if not already configured

gh auth login
gh extension install github/gh-stack

Prerequisites

Git: Normal Git operations still apply.
Homebrew: Required for this installation method.
GitHub CLI: gh must already be installed.
GitHub authentication: An authenticated gh session.
gh-stack extension: gh stack must already be installed and ready to use.

Homebrew installs only ghs. GitHub CLI, authentication and the gh-stack extension are managed separately. ghs is a compiled Go executable for macOS and Linux on Intel and ARM. You do not need Go or jq installed to run it.

Installation happens in your terminal. There is no browser installer, no curl-to-shell script, and no native Windows package.

Upgrade after installation

brew update
brew upgrade peterlapin/ghs/ghs

Uninstall ghs

brew uninstall peterlapin/ghs/ghs
brew untap peterlapin/ghs

Removing ghs leaves your GitHub CLI and extension setup in place.

Command reference

Short commands. Explicit behaviour.

Bare add detects a parent or guides you through creating a layer. Explicit add arguments pass through to GitHub Stack. By default, submit also opens the current branch’s PR after a successful submission. Use --interactive for the original submit behavior.

Mapping of ghs commands to the gh stack commands they run
Command	Runs	Purpose
`ghs init`Initialize a stack	`gh stack init`	Initialize a stack
`ghs add`Attach this branch or create the next layer	`Detect or prompt, then gh stack add`	Attach this branch or create the next layer
`ghs add <arguments>`Pass explicit arguments directly to upstream	`gh stack add <arguments>`	Pass explicit arguments directly to upstream
`ghs create/ ghs c`Add a layer at the top	`gh stack add`	Add a layer at the top
`ghs ls`Show a compact stack view	`gh stack view --short`	Show a compact stack view
`ghs view`View the stack	`gh stack view`	View the stack
`ghs checkout/ ghs co`Check out a stack or layer	`gh stack checkout`	Check out a stack or layer
`ghs switch`Choose a branch interactively	`gh stack switch`	Choose a branch interactively
`ghs up`Move toward the top	`gh stack up`	Move toward the top
`ghs down`Move toward the trunk	`gh stack down`	Move toward the trunk
`ghs top`Jump to the top layer	`gh stack top`	Jump to the top layer
`ghs bottom`Jump to the bottom layer	`gh stack bottom`	Jump to the bottom layer
`ghs trunk`Check out the trunk	`gh stack trunk`	Check out the trunk
`ghs restack/ ghs r`Rebase stack branches locally	`gh stack rebase --no-trunk`	Rebase stack branches locally
`ghs rebase`Fetch and rebase the stack	`gh stack rebase`	Fetch and rebase the stack
`ghs sync`Synchronize local and remote state	`gh stack sync`	Synchronize local and remote state
`ghs submit/ ghs s`Create draft PRs and open the current PR	`gh stack submit --auto && gh pr view --web`	Create draft PRs and open the current PR
`ghs submit --interactive/ ghs s --interactive`Use the original PR details editor without opening the browser	`gh stack submit`	Use the original PR details editor without opening the browser
`ghs push`Push active stack branches	`gh stack push`	Push active stack branches
`ghs reshape`Restructure the stack interactively	`gh stack modify`	Restructure the stack interactively
`ghs merge`Merge stacked PRs	`gh stack merge`	Merge stacked PRs
`ghs unstack`Remove stack tracking and grouping	`gh stack unstack`	Remove stack tracking and grouping

Behaviour notes

Bare ghs add attaches an untracked branch above its nearest tracked ancestor. If no unique parent can be inferred from Git history, it asks you to choose one. Attachment requires a clean working tree and a parent at the top of its stack.
On a tracked stack tip, ghs add asks for staged changes (the default) or all changes, then a new branch name and a separate commit message. All includes untracked files; staged leaves other changes untouched.
If the tracked tip has no commits beyond its parent, gh-stack commits on that branch. ghs explains this and skips the branch-name prompt. Adding in the middle of a stack requires ghs reshape.
Guided add reads gh-stack's local metadata directly. gh-stack performs commits and stack writes. Explicit add arguments and create/c keep their original behavior. No Go installation or jq is needed to run ghs.
submit --interactive uses the original gh stack submit behavior, with the PR details editor in an interactive terminal and no automatic browser opening. ghs removes --interactive and forwards other arguments unchanged; place it before --.
submit uses --auto, which skips the PR details editor and creates new PRs as drafts. On success, the current branch's PR opens in your system browser.
Existing PRs keep their draft status. Pass --open to mark PRs ready for review. Help and failed submissions never open the browser; a browser failure returns a nonzero exit status after submission succeeds.
sync can push changes. It is not fetch-only.
restack operates across the stack locally by default. Use --upstack or --downstack to narrow its scope.
create adds at the top; it does not insert a branch anywhere in the stack.
reshape opens the underlying interactive restructuring interface, not a commit-amend operation.
Continue using ordinary git add and git commit.

How it works

Stacking PRs with your existing Git workflow.

Stacked pull requests split a larger change into smaller PRs that build on each other. Keep working on the next branch while an earlier PR is in review. ghs shortens the commands for this workflow, while GitHub Stack manages the branches and pull requests.

01
Run a ghs command
You type a short, memorable name in your terminal.
02
ghs prepares the command
Aliases map to gh stack commands. Bare add detects a parent or asks which changes, branch name, and commit message to use.
03
GitHub Stack performs the operation
The underlying command does the Git work and maintains stack tracking state.

ghs started as a small Bash wrapper: simple aliases that translated ghs commands into gh stack commands. As guided branch creation, parent detection, and interactive workflows grew, we ported it to Go to keep that logic easier to maintain and test. It still delegates commits and stack management to GitHub Stack.

No additional stack engine, synthetic workspace branch or separate authentication. GitHub Stack remains responsible for stack tracking and Git operations.

ghs forwards command output and arguments. By default, submit skips the PR details editor with --auto, then runs gh pr view --web after submission succeeds. If opening the browser fails, the command reports that failure even though the PR has already been submitted. Use ghs submit --interactive to run the original submit command without --auto or automatic browser opening.