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

code

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 Branches

bash

# 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"

<rules>

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)

</rules>

Addressing Review Feedback

Single PR: Navigate to branch, modify directly

bash

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

Multiple PRs in stack: Use absorb from top

bash

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

Graphite routes changes to correct branches based on file history.

Reorganizing Stacks

bash

# 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

bash

# Current branch + downstack
gt submit

# Entire stack
gt submit --stack

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

Stack Visualization

bash

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

# Visual tree
gt ls

# Recent history
gt log

Sync and Maintenance

bash

# 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

</references>