graphite-stacks

# Graphite Stacks

Trunk-based development with stacked PRs using Graphite CLI.

<when_to_use>

- Creating or managing branch stacks
- Submitting stacked PRs
- Reorganizing branch relationships
- Addressing PR feedback across a stack
- Recovering from stack corruption
- Any `gt` command usage

</when_to_use>

## Core Principle

**Use `gt` commands exclusively.** Mixing `git` and `gt` causes sync issues and divergent stacks. The only exception: `git add` for staging (or use `-a` flags).

## This, Not That

| Task | This | Not That |
| ---- | ---- | -------- |
| Create branch | `gt create 'name' -am "msg"` | `git checkout -b name` |
| Commit changes | `gt modify -acm "msg"` | `git commit -m "msg"` |
| Push to remote | `gt submit` | `git push` |
| Rebase stack | `gt restack` | `git rebase` |
| View stack | `gt status` or `gt ls` | `git log --graph` |
| Switch branches | `gt checkout` | `git checkout` |
| Amend commit | `gt modify -a` | `git commit --amend` |
| Multi-PR feedback | `gt top && gt absorb -a` | Cherry-pick commits manually |

## Stack Lifecycle

```
Create stack → Implement features → Submit PRs → Address feedback → Merge
     │              │                  │               │            │
     ▼              ▼                  ▼               ▼            ▼
 gt create     gt modify -acm     gt submit      gt absorb     gt sync
```

## Creating Stacks

```bash
# New branch with staged changes
gt create 'feature/step-1' -am "feat: first step"

# Continue stacking
gt create 'feature/step-2' -am "feat: second step"
gt create 'feature/step-3' -am "feat: third step"

# Insert branch between current and child
gt create 'feature/step-1.5' --insert -am "feat: inserted step"
```

## Navigation

| Command | Action |
| ------- | ------ |
| `gt up` | Move up the stack (toward children) |
| `gt down` | Move down the stack (toward parent) |
| `gt top` | Jump to stack top |
| `gt bottom` | Jump to stack bottom |
| `gt checkout` | Interactive branch picker |

## Modifying