Getting Started

GitStack keeps fast-moving work split into small, ordered reviews on a single branch. This guide takes you from a fresh install to your first landed stack.

Install the CLI#

Install gs with the one-line installer:

curl -fsSL https://gitstack.sh/install.sh | sh

The installer puts gs in ~/.local/bin by default, so no sudo is needed, and it asks before touching your PATH. Run it from a terminal and it prompts for the install location; in CI it uses the defaults silently. Set GITSTACK_INSTALL_DIR to pick another directory, such as /usr/local/bin.

Or grab it from Homebrew:

brew install alethi-dev/tap/gs

Verify the install:

gs --version

Install the agent skill#

If a coding agent writes some of your code, give it the gs skill before it touches a GitStack repo:

gs skill install ~/.claude/skills/

The skill teaches the agent the same workflow this guide teaches you: commit through gs, carve commits into reviews, respond to threads, and land the stack. Without it, agents fall back on the raw git writes they learned everywhere else, and those bypass the stack tracking. The path above is where Claude Code looks for skills. Pass a different directory for another agent, or run the command with no path to print the skill to stdout and wire it up yourself.

You only install it once. When you upgrade gs, it updates the installed skill on its next run and prints one line saying so. It leaves a copy you have edited alone and reminds you instead. An older gs never replaces a skill written by a newer one, and a gs you built from source never updates it on its own. To get only the reminder, add this to ~/.config/gs/config.toml:

[skill]
auto_refresh = false

Sign in#

gs login opens a browser handshake against gitstack.sh and stores a session token locally:

gs login
gs whoami

If you work as more than one identity on the same machine, say a personal account and a work account, sign each one into its own named profile:

gs login --profile work
gs auth list
gs auth use work --repo   # this repo always acts as "work"

gs auth list shows every profile and which one answers in the current repo. Configuration & files covers how profiles are stored and how gs picks one per command.

Clone a repo or bring your own#

Clone an existing repo from the server:

gs clone acme/payments

Or turn a directory you already have into a GitStack repo:

gs init --repo payments

Or import a repository you already host on GitHub.

gs repo import github acme/payments

The import creates a linked repo on GitStack and prints its clone URL. GitStack becomes the system of record; the GitHub copy stays connected as a mirror, so issues, comments, and CI checks flow both ways.

Make your first stack#

A branch holds a stack of reviews; each review is a contiguous slice of commits. Work in small commits, then carve them into reviews:

gs switch -c add-billing

gs add internal/billing/model.go
gs commit -m "billing: subscription model"

gs add internal/api/billing.go
gs commit -m "billing: POST /api/billing"

gs stack --commits

Carve the commits into reviews bottom-up. The create that reaches the branch tip pushes the branch and manifest for you:

gs review create c1 -t "billing: subscription model"
gs review create -t "billing: POST /api/billing endpoint"

Check the result. The stack should read like a story:

gs stack

Respond to review feedback#

Comments live on reviews. Read the unresolved threads, fix, and push:

gs review comments r1 --unresolved

gs add internal/billing/model.go
gs amend --no-edit --resolves 01H8
gs push

Editing a mid-stack review is safe because gs amend rewrites that review's commit and rebases everything above it for you.

Land it#

Reviews land bottom-up. Land one at a time or the whole stack:

gs submit r1
gs submit --stack

When every review on the branch has landed, clean up:

gs cleanup

Where to go next#