Graphite CLI

Live Docs Fallback

For edge cases or latest features not covered here: https://graphite.com/docs/llms-full.txt

Key Concepts

• Stack: Linear chain of branches, each = 1 PR, building on previous
• Trunk: Main integration branch (main/develop)
• Upstack: Branches further from trunk (children)
• Downstack: Branches closer to trunk (parents)
• Parent/Child: Each branch has one parent; children depend on parent changes

Prerequisites

Before using Graphite:

1. Install: brew install withgraphite/tap/graphite-cli
2. Authenticate: gt auth (GitHub App or PAT)
3. Initialize: repo must have trunk configured (auto-detected on first use)

Quick Decision Trees

"I need to navigate my stack"

• Up one branch: gt up or gt u
• Down one branch: gt down or gt d
• Jump to stack top: gt top or gt t
• Jump to stack bottom: gt bottom or gt b
• Checkout specific branch: gt checkout <branch> or gt co <branch>
• See full stack state: gt log or gt ls (short)

"I need to modify code"

• Add to current branch: gt modify --all or gt m -a
• Add to specific downstack branch: gt modify --into <branch>
• Split branch into multiple: gt split or gt sp
• Squash commits: gt squash or gt sq
• Auto-distribute changes to relevant commits: gt absorb or gt ab
• Rename current branch: gt rename <new-name>

"I need to reorganize branches"

• Move branch to new parent: gt move
• Merge branch into parent: gt fold
• Delete branch, keep changes: gt pop
• Reorder branches in stack: gt reorder
• Delete branch (close PR): gt delete --close

"I need to sync/submit"

• Update trunk + restack all: gt sync
• Submit current branch PR: gt submit
• Submit entire stack: gt ss (alias: gt submit --stack)
• Update PR without new PRs: gt submit --update-only
• Fetch teammate's stack: gt get <branch>
• Track existing git branch: gt track <branch> or gt tr

"Something went wrong"

• Undo last Graphite action: gt undo
• Cancel in-progress rebase: gt abort
• Continue after resolving conflicts: gt continue
• Check what went wrong: gt info

"Merge conflicts during sync"

1. gt sync encounters conflict
2. Resolve conflicts in affected files
3. git add <resolved-files>
4. gt continue
5. If more conflicts, repeat 2-4
6. If hopeless, gt abort to restore pre-sync state

Command Reference

See references/commands.md for full command details.

Common Workflows

See references/workflows.md for step-by-step guides.

Best Practices

See references/best-practices.md for team recommendations.

Troubleshooting