using-git-spice

# Using git-spice

## Overview

**git-spice (`gs`) is a CLI tool for managing stacked Git branches and their Change Requests.**

Core principle: git-spice tracks branch relationships (stacks) and automates rebasing/submitting dependent branches.

## Key Concepts

**Stack terminology:**
- **Stack**: All branches connected to current branch (both upstack and downstack)
- **Upstack**: Branches built on top of current branch (children and descendants)
- **Downstack**: Branches below current branch down to trunk (parents and ancestors)
- **Trunk**: Main integration branch (typically `main` or `master`)

**Example stack:**
```
┌── feature-c     ← upstack from feature-b
├── feature-b     ← upstack from feature-a, downstack from feature-c
├── feature-a     ← downstack from feature-b
main (trunk)
```

When on `feature-b`:
- **Upstack**: feature-c
- **Downstack**: feature-a, main
- **Stack**: feature-a, feature-b, feature-c

## Quick Reference

| Task | Command | Notes |
|------|---------|-------|
| **Initialize repo** | `gs repo init` | Required once per repo. Sets trunk branch. |
| **Create stacked branch** | `gs branch create <name>` | Creates branch on top of current. Use `gs bc` shorthand. |
| **View stack** | `gs log short` | Shows current stack. Use `gs ls` or `gs log long` (`gs ll`) for details. |
| **Submit stack as PRs** | `gs stack submit` | Submits entire stack. Use `gs ss` shorthand. |
| **Submit upstack only** | `gs upstack submit` | Current branch + children. Use `gs us s` shorthand. |
| **Submit downstack only** | `gs downstack submit` | Current branch + parents to trunk. Use `gs ds s` shorthand. |
| **Rebase entire stack** | `gs repo restack` | Rebases all tracked branches on their bases. |
| **Rebase current stack** | `gs stack restack` | Rebases current branch's stack. Use `gs sr` shorthand. |
| **Rebase upstack** | `gs upstack restack` | Current branch + children. Use `gs us r` shorthand. |
| **Move branch to new base** | `gs upstack onto <base>` | Moves c