graphite-cli

# 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 `main` or `master`) 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.

1.  **Authenticate:** Run `gt auth` to connect the CLI to your GitHub account via an auth token.
2.  **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:
1.  Checkout the trunk: `gt checkout main`
2.  Make code edits.
3.  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:
1. Navigate to the top branch of the stack (`part-3`).
2. 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:
1. Edit the relevant files.
2. Run `gt modify -a` to amend the commit with your changes.
3. Run `gt submit` to 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`:**
1.  Fetches the latest remote state.
2.  Pulls the latest changes into the trunk branch (`main`).
3.  **Restacks** (rebases) all of your open branches onto the updated trunk.
4.  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:
1.  **Resolve Conflicts:** Open the files listed in the error message and resolve the conflicts manually.
2.  **Stage Changes:** Mark the conflicts as resolved by running `git add .`.
3.  **Continue:** Run `gt continue` to allow Graphite to complete the original `sync` or `modify` operation.

---

## 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.