Graphite (gt) Skill
This skill provides instructions for navigating branches and restacking stacks using Graphite (gt).
Core Principles
- Strictly Prohibited: NEVER run
gt ss,gt submit, orgt squash. These commands are forbidden. - Navigation: Use
gtcommands to move between branches in a stack. - Maintenance: Use
gt restackfor local stack maintenance andgt getorgt syncfor syncing from remote.
Branch Navigation
Use these commands to navigate through a stack of branches:
| Command | Action |
|---|---|
gt up | Move to the branch immediately above the current one in the stack. |
gt down | Move to the parent of the current branch. |
gt prev | Move to the previous branch in the stack, as ordered by gt log. |
gt next | Move to the next branch in the stack, as ordered by gt log. |
gt top | Move to the tip branch of the current stack. |
gt bottom | Move to the branch closest to trunk in the current stack. |
gt ls | Display all tracked branches and their dependency relationships in a short format. |
Stack Management
Maintain your stack with these commands:
| Command | Action |
|---|---|
gt restack | Ensure each branch in the current stack has its parent in its Git commit history, rebasing if necessary. This maintains the local stack and does NOT reach out to upstream. |
gt get | Sync a specific branch or stack from remote (trunk to branch). If no branch is provided, it syncs the current stack. |
gt sync | Sync all branches (including trunk) from remote and prompt to delete merged branches. |
Branch Management
Use these commands to manage branches within your stack.
| Command | Action |
|---|---|
gt create <branch-name> | Create a new branch with the given name and stack it on top of the current one. Always follow the /gt-create workflow. |
gt move | Rebase the current branch onto a target branch and restack descendants. Use --onto <target-branch> to avoid interactive mode. |
gt split | Split the current branch into multiple branches. This command is highly interactive. |
Commit Management
Use gt modify to manage commits within your stack. It automatically restacks descendants.
| Command | Action |
|---|---|
gt modify --amend | Amend the head commit of the current branch. |
gt modify -c | Create a new commit on the current branch. Preferred for adding new changes while keeping history clean. |
Dealing with Interactivity
Many Graphite commands (gt modify, gt move, gt split, gt restack) are interactive by default, opening selectors, editors, or specialized menus.
- For the Agent: Avoid using these commands in an interactive way. If a command requires user input that cannot be provided via flags (e.g., resolving complex rebase conflicts), stop and notify the user.
- Rebase Conflicts: If
gt restackorgt movehits a conflict, Graphite will pause. Follow these steps to resolve:
1. Locate Conflicts: Use git status or look at the error output to identify files with merge conflicts. 2. Edit Files: Open the conflicting files and resolve the merge markers (<<<<<<<, =======, >>>>>>>). Ensure the code is functionally correct and includes necessary changes from both sides. 3. Stage Changes: Run gt add -A (or git add <file>) to mark the conflicts as resolved. 4. Continue: Run gt continue to resume the restack process. IMPORTANT: NEVER use git rebase --continue as Graphite tracks its own state. 5. Verify: Once the restack completes, run tests to ensure the merged state is stable.
- Interactive Selectors: Prefer providing explicit branch names or flags (like
--ontoforgt move) to avoid interactive selectors.
Common Fixes & Lessons
Using Graphite over Git
The Problem: Using standard git commit or git commit --amend fails to update Graphite's internal stack metadata and does not trigger automatic restacking of descendants. This can lead to a desynchronized stack where Graphite is unaware of the new commits or changes.
The Solution: Always prefer gt commands over their standard git counterparts for commit and branch management.
- Creating a new branch: Use
gt create <branch-name>instead ofgit checkout -b <branch-name>. - Creating a new commit: Use
gt modify -c -m "message"instead ofgit commit -m "message". - Amending a commit: Use
gt modify --amendinstead ofgit commit --amend. - Staging and committing everything: Use
gt modify -cam "message"instead ofgit commit -am "message".
Benefits:
- Metadata Integrity: Graphite keeps its internal view of the stack consistent.
- Automatic Restacking: Descendant branches are automatically updated if you change a parent branch.
- Visual Clarity: Graphite's CLI output stays accurate and helpful.
Misplaced Commits
If you accidentally commit a change to the wrong branch in a stack:
- Stash uncommitted changes: If you have uncommitted work,
git stashto keep it safe. - Move the change to a new branch (if the commit belongs in its own new branch):
1. gt create <new-branch> to safely move the head. 2. gt down to move back to the parent. 3. git reset --hard HEAD~1 (Safe now because the commit is preserved in the new branch).
- Move to an existing branch:
1. git reset HEAD~1 (Soft reset to keep changes in the working tree). 2. gt down/gt up to the target branch. 3. gt modify -c or gt modify --amend to incorporate the changes.
- Restore stashed changes:
git stash popto resume your work. - Repair the stack: Move back to the tip and run
gt restackto ensure all descendant branches are updated with the parent's new state.
Prohibited Commands
[!CAUTION] DO NOT use the following commands under any circumstances: -gt ss-gt submit-gt squash
These commands are strictly forbidden to ensure that PR submission, updates, and branch squashing are handled manually or through specified workflows.