Git Spice Skill

This skill helps you manage stacked Git branches using git-spice (

gs

When to Use This Skill

Use this skill when the user wants to:

• Create a new feature branch ("create a branch", "new branch called X")
• Switch to another branch ("switch branch", "checkout branch")
• Update a branch with latest main ("rebase my branch", "update from main")
• Create a pull request ("create PR", "submit PR", "open pull request")
• Manage multiple related changes ("I have several related changes")
• Work with stacked branches for large features broken into reviewable chunks
• Navigate up/down through branch stacks
• Submit multiple related PRs as a stack
• Manage 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)

gs branch create

gs bc

gs branch checkout

gs bco

gs branch submit

gs bs

gs branch restack

gs br

gs branch delete

gs bd

gs branch onto

gs bon

gs branch edit

gs be

gs stack submit

gs ss

gs stack restack

gs sr

gs upstack submit

gs uss

gs upstack restack

gs usr

gs downstack submit

gs dss

gs repo sync

gs rs

gs repo init

gs ri

gs commit create

gs cc

gs commit amend

gs ca

gs log short

gs ls

gs log long

gs ll

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