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

Stack Lifecycle

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

Creating Stacks

# 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

Modifying Branches

# Amend current branch (stages all)
gt modify -a

# New commit within same branch
gt modify -acm "fix: address review feedback"

# Commit to a different branch in the stack
git add path/to/file.ts
gt modify --into target-branch -m "feat: add file"

ALWAYS:

• Use gt create for new branches
• Use gt modify for commits
• Use gt submit to push
• Use gt restack after parent changes
• Check gt status when uncertain

NEVER:

• Mix git commit/push/rebase with gt workflows
• Force push without understanding stack state
• Use git rebase -i (breaks Graphite metadata)

Addressing Review Feedback

Single PR: Navigate to branch, modify directly

gt checkout target-branch
gt modify -acm "fix: address review comment"
gt submit

Multiple PRs in stack: Use absorb from top

gt top
git add .
gt absorb -a
gt submit --stack

Graphite routes changes to correct branches based on file history.

Reorganizing Stacks

# Move branch to different parent
gt move --onto new-parent

# Move specific branch
gt move --source branch-name --onto target

# After reorganization
gt restack

Submitting

# Current branch + downstack
gt submit

# Entire stack
gt submit --stack

# Non-interactive (automation)
gt submit --no-interactive

Stack Visualization

# JSON with parent relationships (preferred for scripts)
gt status

# Visual tree
gt ls

# Recent history
gt log

Sync and Maintenance

# Pull trunk, rebase stacks, clean merged
gt sync

# Rebase branches onto updated parents
gt restack

# Undo last gt operation
gt undo

When Things Go Wrong

Stack corruption symptoms:

• Branches appear as siblings instead of parent-child
• PRs contain wrong files
• gt status shows unexpected structure

See recovery.md for step-by-step recovery procedures.

• commands.md - Quick command reference
• recovery.md - Stack corruption recovery