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 documentation
run_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-interactive
gt s --no-interactive or gt s --stack --no-interactive
gt 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

graphite