git-spice CLI

git-spice (gs) is a CLI tool for managing stacked Git branches. It tracks relationships between branches, enables easy navigation, and creates stacked Pull Requests on GitHub or Merge Requests on GitLab.

Key Concepts

• Stack: Collection of branches stacked on top of each other
• Trunk: The default branch (main/master) with no base
• Upstack: Branches above the current branch
• Downstack: Branches below the current branch (not including trunk)
• Restacking: Rebasing a branch onto its base to maintain linear history

Command Reference

Repository Commands (gs repo / gs r)

Branch Commands (gs branch / gs b)

Stack Commands (gs stack / gs s)

Upstack Commands (gs upstack / gs us)

Downstack Commands (gs downstack / gs ds)

Commit Commands (gs commit / gs c)

Navigation Commands

Log Commands (gs log / gs l)

Add --all to show all stacks, not just the current one. Add --json for machine-readable output.

Authentication (gs auth)

Rebase Commands (gs rebase / gs rb)

Common Workflows

Create a New Stack

# Start from trunk
gs trunk

# Create first feature branch
git add file.txt
gs branch create feat1

# Stack another branch on top
git add another.txt
gs branch create feat2

Submit a Stack for Review

# Submit entire stack
gs stack submit

# Or submit with auto-filled PR info
gs stack submit --fill

Modify Mid-Stack and Update

# Navigate to the branch to modify
gs down  # or: gs bco feat1

# Make changes and commit
git add file.txt
gs commit create -m "fix typo"

# Submit updates to all CRs
gs stack submit

Sync After Merges

# Pull latest, delete merged branches, restack remaining
gs repo sync

Move a Branch to Different Base

# Move current branch and upstack to main
gs upstack onto main

# Move only current branch (leave upstack in place)
gs branch onto main

Split a Branch

# Interactively split current branch at commit boundaries
gs branch split

Common Flags

• --fill / -c: Auto-fill CR info from commits
• --draft / --no-draft: Set CR draft status
• --force: Force push (override safety checks)
• --update-only: Only update existing CRs, don't create new ones
• -n / --dry-run: Show what would happen without doing it
• --no-prompt: Disable interactive prompts

Configuration

Set options with git config:

# Create branches without committing by default
git config spice.branchCreate.commit false

# Add prefix to all created branches
git config spice.branchCreate.prefix "user/"

# Create CRs as drafts by default
git config spice.submit.draft true

# Open browser when CR is created
git config spice.submit.web created

# Add default labels to all CRs
git config spice.submit.label "needs-review"

# Add default reviewers
git config spice.submit.reviewers "alice,myorg/team"

Tips

• Use --help on any command to see its shorthand
• Interactive prompts provide fuzzy search for branch selection
• Navigation commands accept -n to print target without switching
• Use gs bco without arguments for an interactive branch picker