Git Spice Skill

This skill helps you manage stacked Git branches using git-spice (gs), a CLI tool for creating, navigating, and submitting branch stacks as pull requests.

When to Use This Skill

Use this skill when:

• Creating stacked branches for large features broken into reviewable chunks
• Navigating up/down through branch stacks
• Submitting multiple related PRs as a stack
• Rebasing and restacking branches after upstream changes
• Managing branch dependencies and PR chains on GitHub/GitLab

Core Concepts

Stacked Branches: A series of branches where each branch is based on the previous one, forming a dependency chain rooted at trunk (main/master).

    ┌── feat3 (#3)    <- top of stack
  ┌─┴ feat2 (#2)
┌─┴ feat1 (#1)        <- bottom of stack
main                  <- trunk

Trunk: The main development branch (main, master, or configured trunk).

Upstack/Downstack: Branches above/below the current branch in the stack.

Quick Start

1. Initialize Repository

gs repo init

This sets up git-spice tracking in your repository. You'll be prompted to select the trunk branch and remote.

2. Create a Branch Stack

# Start from trunk
git checkout main

# Create first branch in stack
gs branch create feat1 -m "Add user model"

# Create second branch stacked on feat1
gs branch create feat2 -m "Add user API"

# Create third branch stacked on feat2
gs branch create feat3 -m "Add user tests"

3. Navigate the Stack

gs up        # Move up one branch (u)
gs down      # Move down one branch (d)
gs top       # Jump to top of stack (U)
gs bottom    # Jump to bottom of stack (D)
gs trunk     # Return to trunk branch

4. View Your Stack

gs log short    # List all tracked branches (ls)
gs log long     # Show branches with commits (ll)

5. Submit PRs

gs stack submit     # Submit entire stack as PRs (ss)
gs branch submit    # Submit current branch only (bs)
gs upstack submit   # Submit current and all above (uss)
gs downstack submit # Submit current and all below (dss)

6. Sync and Restack

gs repo sync       # Pull latest, delete merged branches (rs)
gs stack restack   # Rebase all branches onto latest (sr)

Command Reference (Shorthands)

Command	Shorthand	Description
gs branch create	gs bc	Create new branch
gs branch checkout	gs bco	Switch to branch
gs branch submit	gs bs	Submit branch as PR
gs branch restack	gs br	Rebase branch on base
gs branch delete	gs bd	Delete branch
gs branch onto	gs bon	Move branch onto another
gs branch edit	gs be	Interactive rebase
gs stack submit	gs ss	Submit entire stack
gs stack restack	gs sr	Restack entire stack
gs upstack submit	gs uss	Submit upstack
gs upstack restack	gs usr	Restack upstack
gs downstack submit	gs dss	Submit downstack
gs repo sync	gs rs	Sync with remote
gs repo init	gs ri	Initialize repo
gs commit create	gs cc	Create commit
gs commit amend	gs ca	Amend commit
gs log short	gs ls	List branches
gs log long	gs ll	List with commits

Common Workflows

Creating a Feature Stack

# Start from updated trunk
gs trunk
git pull

# Create logical branches for each reviewable piece
gs bc api-models -m "Add data models for new API"
gs bc api-handlers -m "Implement API handlers"
gs bc api-tests -m "Add API integration tests"

# View your stack
gs ll

Updating After Review Feedback

# Navigate to branch that needs changes
gs bco api-handlers

# Make changes, then amend or create new commit
gs ca  # amend current commit
# or
gs cc -m "Address review feedback"

# Restack all branches above to incorporate changes
gs usr  # upstack restack

Syncing with Upstream Changes

# Sync repo - pulls trunk, deletes merged branches
gs rs

# Restack all tracked branches onto new trunk
gs repo restack
# or for just current stack:
gs sr

Moving a Branch

# Move current branch onto a different base
gs bon main           # Move onto main directly
gs bon other-feature  # Move onto another branch

# Insert a new branch in the middle of a stack
gs bc new-branch --insert  # Restacks upstack onto new branch

Handling Conflicts

When restacking encounters conflicts:

# Resolve conflicts in your editor
git status  # See conflicted files
# ... fix conflicts ...
git add <resolved-files>

# Continue the restack operation
gs rebase continue  # (gs rbc)

# Or abort if needed
gs rebase abort     # (gs rba)

Submitting PRs

# Submit all branches in stack as linked PRs
gs ss

# Submit with draft PRs
gs ss --draft

# Submit only current branch
gs bs

# Update PR after changes
gs bs  # Re-run submit updates existing PR

Branch Operations

Track Existing Branches

# Track a single branch
gs branch track feature-branch --base main

# Track all branches in a downstack
gs downstack track

Split and Squash

# Split current branch into multiple commits
gs branch split

# Squash branch into single commit
gs branch squash

Delete Branches

# Delete a single branch
gs bd feature-branch

# Delete entire upstack
gs upstack delete

# Delete entire stack
gs stack delete

Authentication

gs auth login   # Authenticate with GitHub/GitLab
gs auth status  # Check current auth status
gs auth logout  # Clear credentials

Configuration

Git-spice uses git config for settings:

# Set branch name prefix
git config spice.branchCreate.prefix "username/"

# Configure navigation comment style
git config spice.submit.navigationComment multiple

# View all spice config
git config --get-regexp spice

Troubleshooting

Branch Not Tracked

# Track an existing branch
gs branch track my-branch --base main

Rebase Conflicts

# After resolving conflicts
gs rebase continue

# To abort and try different approach
gs rebase abort

Out of Sync with Remote

gs repo sync    # Fetch and sync
gs repo restack # Restack all branches

Force Push After Restack

After restacking, branches need force push:

gs bs --force  # Submit handles force push
# or manually:
git push --force-with-lease

Reference Documentation

For detailed information on specific topics, see:

• Command Reference - Complete command documentation
• Workflows - Advanced workflow patterns

Key Principles

1. Atomic branches: Each branch should be one logical, reviewable change
2. Stack from trunk: Build stacks starting from main/master
3. Restack often: Keep branches rebased on latest changes
4. Submit together: Use gs ss to create linked PRs
5. Sync regularly: Use gs rs to stay current with upstream