Work with Graphite (gt) for stacked PRs - creating, navigating, and managing PR stacks.

Graphite Skill Work with Graphite ( gt ) for creating, navigating, and managing stacked pull requests. Quick Reference I want to... Command Create a new branch/PR gt create branch name m "message" Amend current branch gt modify m "message" Navigate up the stack gt up Navigate down the stack gt down Jump to top of stack gt top Jump to bottom of stack gt bottom View stack structure gt ls Submit stack for review gt submit no interactive Rebase stack on trunk gt restack Change branch parent gt track parent <branch Rename current branch gt rename <new name Move branch in stack gt move What Makes a Good PR? In roughly descending order of importance: Atomic/hermetic independent of other changes; will pass CI and be safe to deploy on its own Narrow semantic scope changes only to module X, or the same change across modules X, Y, Z Small diff (heuristic) small total diff line count Do NOT worry about creating TOO MANY pull requests. It is always preferable to create more pull requests than fewer. NO CHANGE IS TOO SMALL: tiny PRs allow for the medium/larger sized PRs to have more clarity. Always argue in favor of creating more PRs, as long as they independently pass build. Branch Naming Conventions When naming PRs in a stack, follow this syntax: terse stack feature name/terse description of change For example, a 4 PR stack: Creating a Stack Basic Workflow 1. Make changes to files 2. Stage changes: git add <files 3. Create branch: gt create branch name m "commit message" 4. Repeat for each PR in the stack 5. Submit: gt submit no interactive Handle Untracked Branches (common with worktrees) Before creating branches, check if the current branch is tracked: If you see "ERROR: Cannot perform this operation on untracked branch": Option A (Recommended): Track temporarily, then re parent 1. Track current branch: gt track p main 2. Create your stack normally with gt create 3. After creating ALL branches, re parent your first new branch onto main: Option B: Stash changes and start from main 1. git stash 2. git checkout main && git pull 3. Create new branch and unstash: git checkout b temp working && git stash pop 4. Proceed with gt track p main and gt create Navigating a Stack Modifying a Stack Amend Current Branch Reorder Branches Use gt move to reorder branches in the stack. This is simpler than trying to use gt create insert . Re parent a Stack If you created a stack on top of a feature branch but want it based on main: Rename a Branch Resetting Commits to Unstaged Changes If changes are already committed but you want to re stack them differently: Before Submitting Verify Stack is Rooted on Main Before running gt submit , verify the first PR is parented on main : If the first branch has a parent other than main : Run Validation After creating each PR, run appropriate linting, building, and testing: 1. Refer to the project's CLAUDE.md for specific commands 2. If validation fails, fix the issue, stage changes, and use gt modify Submitting and Updating PRs Submit the Stack Update PR Descriptions After submitting, use gh pr edit to set proper titles and descriptions. IMPORTANT: Never use Bash heredocs for PR descriptions shell escaping breaks markdown tables, code blocks, etc. Instead: 1. Use the Write tool to create /tmp/pr body.md with the full markdown content 2. Use gh pr edit with body file : PR descriptions must include: Stack Context : What is the bigger goal of this stack? What? (optional for small changes): Super terse, focus on what not why Why? : What prompted the change? Why this solution? How does it fit into the stack? Example (for a PR in a 3 PR stack adding a warning feature): Troubleshooting Problem Solution "Cannot perform this operation on untracked branch" Run gt track p main first Stack parented on wrong branch Use gt track p main then gt restack Need to reorder PRs Use gt move Conflicts during restack Resolve conflicts, then git rebase continue Want to split a PR Reset commits ( git reset HEAD^ ), re stage selectively, create new branches Need to delete a branch (non interactive) gt delete <branch f q gt restack hitting unrelated conflicts Use targeted git rebase <target instead (see below) Rebase interrupted mid conflict Check if files are resolved but unstaged, then git add + git rebase continue Advanced: Surgical Rebasing in Complex Stacks In deeply nested stacks with many sibling branches, gt restack can be problematic: It restacks ALL branches that need it, not just your stack Can hit conflicts in completely unrelated branches Is all or nothing hard to be surgical When to Use git rebase Instead of gt restack Use direct git rebase when: You only want to update specific branches in your stack gt restack is hitting conflicts in unrelated branches You need to skip obsolete commits during the rebase Targeted Rebase Workflow Recovering from Interrupted Rebase (Context Reset) If a rebase was interrupted (e.g., Claude session ran out of context): 1. Check status: 2. Read the "unmerged" files they may already be resolved (no conflict markers) 3. If already resolved, just stage and continue: 4. If still has conflict markers , resolve them first, then stage and continue Deleting Branches from a Stack Flags: f / force : Delete even if not merged or closed q / quiet : Implies no interactive , minimizes output After deleting intermediate branches , children are automatically restacked onto the parent. If you need to manually update tracking:

graphite