graphite

Graphite CLI - Stacked PRs Workflow

Graphite CLI (gt) manages stacked branches and PRs from the command line. Instead of one massive PR, break work into a chain of small, reviewable PRs where each builds on the previous.

Docs: https://graphite.com/docs/graphite-cli Stacking overview: https://www.stacking.dev/

When to Use This Skill

Trigger 1: Work Based on Un-Merged Branches

When implementing a feature that depends on code from a branch not yet merged to trunk, use Graphite to formalize the dependency as a stack. This ensures:

• Each PR targets its parent branch, not trunk
• Reviewers see only the incremental diff
• Merging happens bottom-up automatically

Trigger 2: A Change Is Too Large for One PR

Consider splitting into a stack when any of these apply:

• >400 lines changed across the diff
• >3 unrelated concerns (e.g., schema change + business logic + tests + config)
• >5 packages/directories touched with distinct purposes
• Reviewer would need >30 minutes to understand the full context

Splitting strategy - group by concern:

1. Infrastructure/schema changes (migrations, proto files, BUILD files)
2. Core logic / library changes
3. Integration / wiring (API handlers, config)
4. Tests (if substantial enough to warrant a separate PR)

Anti-Patterns

When Graphite is available, always use gt commands instead of raw git:

• Do not use git push — use gt submit or gt ss to push and create/update PRs
• Do not use git checkout -b — use gt create to maintain stack metadata
• Do not rebase manually — use gt modify and let Graphite restack automatically
• Do not use git commit — use gt create (new branch) or gt modify (amend current branch)

Breaking these rules corrupts Graphite's stack metadata and requires manual recovery.

Core Workflow

Starting a Stack

# Ensure trunk is up to date
gt sync

# Create the first branch in the stack
gt create -am "add user schema migration"

# Continue working, create the next branch on top
gt create -am "implement user service logic"

# And the next
gt create -am "add user API handlers"

Each gt create stacks the new branch on top of the current one.

Modifying a Branch

# Amend staged changes to current branch
gt modify -a

# Or add a new commit instead of amending
gt modify -cam "fix edge case in validation"

Modifying a Mid-Stack Branch

# Navigate to the branch
gt checkout <branch-name>
# Or use relative navigation
gt down 2

# Make changes, then amend
gt modify -a
# Graphite automatically restacks all upstack branches

If conflicts arise during restacking:

1. Resolve the conflicts in the files
2. git add .
3. gt continue
4. To abort: gt abort

Submitting the Stack

# Submit entire stack (create/update PRs for all branches)
gt submit --stack
# Shorthand:
gt ss

# Submit only current branch and its downstack
gt submit

# Update only branches that already have PRs
gt ss -u

Syncing with Remote

# Pull trunk, clean merged branches, restack
gt sync

Navigation

Command	Shorthand	Action
gt log		Full stack view with PR status
gt log short	gt ls	Compact branch list
gt checkout <branch>	gt co	Switch to branch
gt up [n]	gt u	Move up n branches (default 1)
gt down [n]	gt d	Move down n branches (default 1)
gt top	gt t	Go to top of stack
gt bottom	gt b	Go to bottom of stack

Reorganizing a Stack

Command	Shorthand	Action
gt split	gt sp	Split current branch into multiple
gt fold		Fold branch into its parent
gt move		Move branch to a new parent
gt reorder		Reorder branches in the stack
gt squash	gt sq	Squash all commits in branch into one
gt absorb	gt ab	Distribute staged changes to downstack branches
gt pop		Delete branch, keep changes in working tree

Splitting a Branch (Common for "PR too large")

gt split interactively splits the current branch's changes into multiple new branches. Use when a single branch has grown to cover multiple concerns.

Alternatively, split manually:

1. gt checkout <big-branch>
2. gt pop (removes branch, keeps changes unstaged)
3. Stage first concern's files, gt create -am "first concern"
4. Stage next concern's files, gt create -am "second concern"
5. Repeat until all changes are committed

Recovery

# Undo the most recent Graphite mutation
gt undo

Collaboration

# Fetch a teammate's stack locally
gt get <branch-name>

# Freeze a branch to prevent edits
gt freeze <branch>
gt unfreeze <branch>

Additional Resources

• references/cli-reference.md - Full CLI command reference
• Online docs: https://graphite.com/docs/cheatsheet