git-spice

# 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

```bash
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

```bash
# 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

```bash
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

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

### 5. Submit PRs

```bash
gs stack submit     # Submit entire stack as PRs (ss)
gs branch submit    # Submit current branch only (bs)
gs upstack submit