aiskillstore Graphite CLI Guide
This skill provides procedural knowledge for working with the Graphite command-line interface (CLI). It covers the entire lifecycle of creating and managing stacked pull requests, from initial setup to advanced stack manipulation.
When to Use This Skill
Activate this skill when a user's request involves using the gt command, managing stacked pull requests, or inquiring about the Graphite workflow. It is designed to handle tasks such as creating branches, submitting PRs, synchronizing with the trunk branch, and modifying the structure of a stack.
Core Concepts
- Stack: A series of small, incremental, and dependent branches. Each branch is a distinct PR, building on the previous one.
- Trunk: The primary branch of the repository (usually
mainormaster) from which all stacks originate and into which they are eventually merged.
I. Initial Setup
To begin using Graphite in a git repository, it must be initialized.
- Authenticate: Run
gt authto connect the CLI to your GitHub account via an auth token. - Initialize Repository: Navigate to the repository root and run
gt init. This command will prompt to select the trunk branch.
II. Core Workflow: Creating & Submitting Changes
This workflow covers the fundamental loop of creating, submitting, and updating branches.
Step 1: Create a Branch
To create a new branch and commit changes, use gt create. This command replaces git add, git commit, and git checkout -b. The new branch will be stacked on the currently checked-out branch.
| Command | Alias/Flags | Description |
|---|---|---|
gt create |
gt c |
Creates a new branch and commits staged changes. |
gt create -m <MSG> |
gt c -m |
Creates a branch with a specific commit message. |
gt create -a |
gt c -a |
Stages all unstaged changes before committing. |
gt create -am <MSG> |
gt c -am |
Combines staging all changes and adding a message. |
Example:
To create a branch from main with all current file changes and a commit message:
- Checkout the trunk:
gt checkout main - Make code edits.
- Create the branch:
gt create -am "feat: Add new user model"
Step 2: Submit for Review
To push a branch (or a stack of branches) and open pull requests on GitHub, use gt submit.
| Command | Alias/Flags | Description |
|---|---|---|
gt submit |
Pushes the current branch, creating or updating its PR. | |
gt submit --stack |
gt ss |
Pushes all branches in the current stack, from trunk up to the current branch, creating/updating a distinct PR for each. |
gt submit -d |
Submits the PR as a draft. | |
gt pr |
Opens the GitHub PR page for the current branch in a browser. |
Example: To submit an entire 3-part stack for review:
- Navigate to the top branch of the stack (
part-3). - Run
gt submit --stack --reviewers alice,bob
Step 3: Modify and Update
To update a branch with feedback, edit the code and use gt modify to amend the commit.
| Command | Alias/Flags | Description |
|---|---|---|
gt modify |
gt m |
Amends the commit on the current branch with staged changes. |
gt modify -a |
gt m -a |
Amends the commit with all staged and unstaged changes. This is the most common update command. |
Example: To apply a requested change to a PR:
- Edit the relevant files.
- Run
gt modify -ato amend the commit with your changes. - Run
gt submitto update the remote PR.
III. Stack Management & Navigation
Visualizing the Stack
To see the dependency structure of your branches, use gt log short.
| Command | Alias | Description |
|---|---|---|
gt log short |
gt ls |
Displays all tracked branches and their dependency relationships in a compact tree format. |
Navigating the Stack
Use these commands to move efficiently between branches in a stack.
| Command | Alias | Function |
|---|---|---|
gt up |
gt u |
Switches to the child branch (upstack). |
gt down |
gt d |
Switches to the parent branch (downstack). |
gt top |
gt t |
Switches to the highest branch (tip) of the current stack. |
gt bottom |
gt b |
Switches to the lowest branch of the current stack. |
gt checkout |
gt co |
Opens an interactive selector to choose any tracked branch. |
IV. Synchronization & Conflict Resolution
Keeping the Stack Up-to-Date
To update your stack with the latest changes from the trunk, use gt sync.
Actions performed by gt sync:
- Fetches the latest remote state.
- Pulls the latest changes into the trunk branch (
main). - Restacks (rebases) all of your open branches onto the updated trunk.
- Prompts to delete any local branches that have been merged or closed remotely.
Resolving Conflicts
If gt sync or gt modify pauses due to a merge conflict, follow these steps:
- Resolve Conflicts: Open the files listed in the error message and resolve the conflicts manually.
- Stage Changes: Mark the conflicts as resolved by running
git add .. - Continue: Run
gt continueto allow Graphite to complete the originalsyncormodifyoperation.
V. Advanced Stack Manipulation
These commands are used to restructure a stack.
| Command | Description |
|---|---|
gt move |
Rebases the current branch and its children onto a new parent. Use this to change a branch's dependency (e.g., gt move --onto main). |
gt fold |
Combines (squashes) the current branch's changes into its parent branch and deletes the current branch. |
gt split |
Splits the current branch into two or more new branches, either by commit or by interactively selecting file hunks. |
gt create --insert |
Creates and inserts a new branch between the current branch and its parent. |
gt absorb |
Automatically applies unstaged changes to the most relevant downstack commits. Useful for distributing feedback fixes across multiple PRs at once. |
Bundled Resources
references/graphite_cli_guide.md: The complete and unabridged guide for the Graphite CLI. Consult this file for detailed explanations of every command and workflow, including collaboration (gt get,gt freeze) and multi-trunk support.