Graphite Workflow Skill
This skill ensures correct usage of Graphite CLI (gt) for managing stacked PRs. When working in a Graphite-enabled workflow, always use gt commands instead of raw git commands for stack-aware operations.
When to Use
Apply this skill when:
- User mentions Graphite, stacking, or
gt - Working on a feature that uses stacked PRs
- Using
execute-issue-graphiteagent - Managing branches in a stack
Critical Rule: gt vs git
| Instead of... | Use... | Why |
|---|---|---|
git commit | gt create -a -m "message" | Creates branch + commit + tracks in stack |
git commit --amend | gt modify -a | Amends AND auto-restacks descendants |
git push | gt submit --no-interactive | Pushes AND creates/updates PRs |
git checkout <branch> | gt checkout <branch> | Stack-aware checkout |
git pull / git rebase | gt sync | Syncs trunk AND rebases entire stack |
Core Commands Quick Reference
# Creating PRs in a stack
gt create -a -m "feat: description" # Stage all, create branch, commit
# Modifying existing PR
gt modify -a # Amend commit, auto-restack upstack
# Submitting to GitHub
gt submit --no-interactive # Current branch + downstack
gt submit --stack --no-interactive # Entire stack
# Navigation
gt up / gt down # Move within stack
gt top / gt bottom # Jump to ends of stack
gt checkout # Interactive picker
# Syncing
gt sync # Fetch trunk, rebase stack, cleanup merged
# Viewing
gt log # Visual stack graph
gt ls # Short listThe Stack Building Workflow
- Write code FIRST - Never create empty branches
- Stage changes -
git add. - Create branch -
gt create -a -m "message" - Repeat for each slice
- Submit stack -
gt submit --stack --no-interactive
When to Use Raw Git
These operations are fine with raw git:
git add- Staging filesgit status- Checking statusgit diff- Viewing changesgit log(for viewing history, not stack structure)
Handling Modifications
When changes are needed to an earlier PR in the stack:
gt checkout <branch-needing-changes>
# Make code changes
git add .
gt modify -a # Amend + auto-restack
gt submit --stack --no-interactive # Push updatesConflict Resolution
# If conflict occurs during sync/restack:
# 1. Fix conflicts in editor
git add .
gt continue
# To abort:
gt abort