Graphite

# Graphite Skill

Work with Graphite (`gt`) for creating, navigating, and managing stacked pull requests.

## Quick Reference

| I want to... | Command |
|--------------|---------|
| Create a new branch/PR | `gt create branch-name -m "message"` |
| Amend current branch | `gt modify -m "message"` |
| Navigate up the stack | `gt up` |
| Navigate down the stack | `gt down` |
| Jump to top of stack | `gt top` |
| Jump to bottom of stack | `gt bottom` |
| View stack structure | `gt ls` |
| Submit stack for review | `gt submit --no-interactive` |
| Rebase stack on trunk | `gt restack` |
| Change branch parent | `gt track --parent <branch>` |
| Rename current branch | `gt rename <new-name>` |
| Move branch in stack | `gt move` |

---

## What Makes a Good PR?

In roughly descending order of importance:

- **Atomic/hermetic** - independent of other changes; will pass CI and be safe to deploy on its own
- **Narrow semantic scope** - changes only to module X, or the same change across modules X, Y, Z
- **Small diff** - (heuristic) small total diff line count

**Do NOT worry about creating TOO MANY pull requests.** It is **always** preferable to create more pull requests than fewer.

**NO CHANGE IS TOO SMALL:** tiny PRs allow for the medium/larger-sized PRs to have more clarity.

Always argue in favor of creating more PRs, as long as they independently pass build.

---

## Branch Naming Conventions

When naming PRs in a stack, follow this syntax:

`terse-stack-feature-name/terse-description-of-change`

For example, a 4 PR stack:

```
auth-bugfix/reorder-args
auth-bugfix/improve-logging
auth-bugfix/improve-documentation
auth-bugfix/handle-401-status-codes
```

---

## Creating a Stack

### Basic Workflow

1. Make changes to files
2. Stage changes: `git add <files>`
3. Create branch: `gt create branch-name -m "commit message"`
4. Repeat for each PR in the stack
5. Submit: `gt submit --no-interactive`

### Handle Untracked Branches (common with worktrees)

Before creating branches, check if the current branch is tracked:

```bash
gt branch info
```

If you see "ERROR: Cannot perform this operation on untracked branch":

**Option A (Recommended): Track temporarily, then re-parent**
1. Track current branch: `gt track -p main`
2. Create your stack normally with `gt create`
3. After creating ALL branches, re-parent your first new branch onto main:
   ```bash
   gt checkout <first-branch-of-your-stack>
   gt track -p main
   gt restack
   ```

**Option B: Stash changes and start from main**
1. `git stash`
2. `git checkout main && git pull`
3. Create new branch and unstash: `git checkout -b temp-working && git stash pop`
4. Proceed with `gt track -p main` and `gt create`

---

## Navigating a Stack

```bash
# Move up one branch (toward top of stack)
gt up

# Move down one branch (toward trunk)
gt down

# Jump to top of stack
gt top

# Jump to bottom of stack (first branch above trunk)
gt bottom

# View the full stack structure
gt ls
```

---

## Modifying a Stack

### Amend Current Branch

```bash
git add <files>
gt modify -m "updated commit message"
```

### Reorder Branches

Use `gt move` to reorder branches in the stack. This is simpler than trying to use `gt create --insert`.

### Re-parent a Stack

If you created a stack on top of a feature branch but want it based on main:

```bash
# Go to first branch of your stack
gt checkout <first-branch>

# Change its parent to main
gt track --parent main

# Rebase the entire stack
gt restack
```

### Rename a Branch

```bash
gt rename new-branch-name
```

---

## Resetting Commits to Unstaged Changes

If changes are already committed bu