Graphite Stacked PRs
Use Graphite CLI (gt) instead of raw git for all branch and PR operations in Graphite-initialized repos.
Detection
A repo is Graphite-initialized if .git/.graphite_repo_config exists. When detected, prefer gt over git for branch/PR workflows.
MCP Tools
The Graphite MCP server (gt mcp) is available. Use the learn_gt and run_gt_cmd tools when available:
learn_gt — look up gt command documentationrun_gt_cmd — execute gt commands directly
Key Concepts
- A stack is a sequence of PRs, each building on its parent
- Each PR must be atomic — self-contained and CI-green independently
- Stacks are visualized with trunk at the BOTTOM:
- Up/Upstack = away from trunk toward leaves
- Down/Downstack = toward trunk/main
PR #3 (top)
|
PR #2
|
PR #1
|
main (trunk)
Command Reference
Branch Navigation
| Command |
Description |
gt checkout [branch] |
Switch branches (interactive picker if no arg) |
gt co main |
Switch to trunk |
gt up [steps] |
Navigate to child branch |
gt down [steps] |
Navigate to parent branch |
gt top |
Jump to top of stack |
gt bottom |
Jump to trunk-closest branch |
Creating & Modifying Branches
| Command |
Description |
gt create -a -m "message" |
Create new branch with staged changes |
gt c --no-interactive -m "message" |
Create new branch (non-interactive) |
gt modify --no-interactive |
Amend current commit |
gt m --no-interactive |
Short form: amend current commit |
gt modify -a |
Amend with staged changes, then restack |
gt modify --commit -a -m "msg" |
Add explicit commit (for review feedback) |
gt delete [name] |
Delete branch and metadata |
gt rename [name] |
Rename branch |
Stack Operations
| Command |
Description |
gt restack |
Rebase dependent branches after changes |
gt sync --no-interactive |
Pull latest main, delete merged branches, rebase |
gt fold |
Merge branch into its parent |
gt split |
Break branch into multiple branches |
gt squash |
Consolidate commits in branch |
gt reorder |
Reorder branches in stack |
gt move --onto <branch> |
Move branch to different parent |
Submitting PRs
| Command |
Description |
gt submit --no-interactive |
Push and create/update PR for current branch |
gt s --no-interactive |
Short form: submit current branch |
gt s --stack --no-interactive |
Submit current + all descendant branches |
gt ss |
Alias for gt submit --stack |
gt s --draft --no-interactive |
Submit as draft PR |
gt submit --reviewers alice,bob |
Assign reviewers |
Viewing
| Command |
Description |
gt log / gt l |
Show stack visualization |
gt log short / gt ls |
Abbreviated stack view |
gt pr [branch] |
Open PR in browser |
gt info [branch] |
Display branch details |
Recovery
| Command |
Description |
gt continue |
Resume halted operation (after conflict resolution) |
gt abort |
Cancel current operation |
gt undo |
Revert last operation |
Git-to-Graphite Translation
| Instead of... |
Use... |
git checkout -b branch |
gt c --no-interactive -m 'message' |
git push |
gt s --no-interactive |
git rebase main |
gt restack |
git commit --amend |
gt m --no-interactive |
git pull origin main |
gt sync --no-interactive |
Workflow Rules
Branch Selection Decision Tree
| Situation |
Action |
| On main? |
Never commit to main. Create new branch: gt c --no-interactive -m 'message' |
| On a branch + changes are related WIP? |
Amend in place: gt m --no-interactive |
| On unrelated branch + independent changes? |
gt co main then create new branch |
| On a branch + changes depend on it? |
Create stacked branch: gt c --no-interactive -m 'message' |
Always Use --no-interactive
All gt commands that support it should use --no-interactive to avoid blocking on prompts. Key commands:
gt c --no-interactive -m 'message'gt m --no-interactivegt s --no-interactive or gt s --stack --no-interactivegt sync --no-interactive
Staging Rules
- Check if working tree is dirty (
git diff)
- Never mix different fixes/features/WIP together
- Stage only one set of related changes using
git add <specific-files>
Commit Messages
Use semantic commit names: feat:, fix:, chore:, refactor:, docs:, test:
Submitting
- Submit WIP as draft:
gt s --draft --no-interactive
- Submit final work:
gt s --no-interactive
- Submit entire stack:
gt s --stack --no-interactive
For PR title/description conventions (Linear ticket, GitHub issue, no customer names), use the creating-pull-requests skill.
Handling Conflicts
# During restack, if conflicts occur:
# 1. Resolve conflicts in the files
# 2. Stage resolved files
git add <resolved-files>
# 3. Continue the operation
gt continue
Completion Criteria
- Working tree must be clean (no unstaged/untracked changes)
- All branches in the stack are submitted
gt log shows the correct stack structure
Creating a Stack (Typical Flow)
# Start from trunk
gt co main
gt sync --no-interactive
# Create first PR
# ... make changes ...
git add <specific-files>
gt c --no-interactive -m 'feat: add database migration'
# Create second PR on top
# ... make changes ...
git add <specific-files>
gt c --no-interactive -m 'feat: add backend service'
# Create third PR on top
# ... make changes ...
git add <specific-files>
gt c --no-interactive -m 'feat: add frontend components'
# Submit entire stack
gt s --stack --no-interactive
# Verify
gt log
Addressing Review Feedback
# Navigate to the PR that needs changes
gt checkout branch-name
# Make changes, stage them
git add <specific-files>
# Amend and restack all branches above
gt m --no-interactive
# Push updates for the whole stack
gt s --stack --no-interactive
lightdash