# Graphite

> Manage Git branches and PRs using Graphite CLI (gt) instead of raw git commands. Use this skill when committing code changes, amending commits, creating branches, or submitting pull requests. Triggers on git commit, git push, creating PRs, amending changes, stacking branches, or any version control workflow.

- Skill: `usefulsoftwareco/graphite` (Agent Skill)
- Install (CLI): `npx skillmds@latest add usefulsoftwareco/graphite`
- Raw SKILL.md: https://api.skillmd.com/api/skills/usefulsoftwareco/graphite/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: usefulsoftwareco (https://skillmd.com/u/usefulsoftwareco)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/usefulsoftwareco/graphite

---


# Graphite CLI Command Reference

## Prefer gt over git

Use `gt` commands instead of their `git` counterparts for commit and branch management. Raw git bypasses Graphite's stack metadata, leaving descendants un-restacked and the CLI's view of the stack out of sync.

| Instead of               | Use                     |
| ------------------------ | ----------------------- |
| `git checkout -b <name>` | `gt create <name>`      |
| `git commit -m "msg"`    | `gt modify -c -m "msg"` |
| `git commit --amend`     | `gt modify --amend`     |
| `git commit -am "msg"`   | `gt modify -cam "msg"`  |

Why: `gt` keeps stack metadata consistent and auto-restacks descendant branches when a parent changes.

## Interactivity (for agents)

Several commands are interactive by default and will hang without a TTY: `gt modify`, `gt move`, `gt split`, `gt restack`, `gt checkout` (no arg), `gt submit`.

- Always pass explicit args/flags: `gt move --onto <branch>`, `gt modify -m "msg"`, `gt checkout <branch>`, `gt submit --no-interactive`.
- Add `--no-interactive` (or `--quiet`) to skip prompts.
- If a command genuinely needs input that can't be supplied via flags (e.g. complex rebase conflict resolution), stop and notify the user rather than guessing.

## Rebase Conflicts

When `gt restack`, `gt move`, `gt sync`, etc. pause on a conflict:

1. `git status` to find conflicted files.
2. Resolve the `<<<<<<<` / `=======` / `>>>>>>>` markers.
3. Stage with `gt add -A` (or `git add <file>`).
4. Run `gt continue` — **never** `git rebase --continue`. Graphite tracks its own rebase state; using raw git desyncs it.
5. Verify the stack once continue completes (`gt log`, run tests).

To bail out: `gt abort`.

## Global Flags

- `--help` - Show help for a command
- `--cwd` - Working directory for operations
- `--debug` - Write debug output
- `--interactive` / `--no-interactive` - Enable/disable prompts (default: enabled)
- `--verify` / `--no-verify` - Enable/disable git hooks (default: enabled)
- `--quiet` - Minimize output, implies `--no-interactive`

## Branch Creation & Modification

### gt create [name]

Create a new branch stacked on current branch with staged changes.

**Flags:**

- `-a, --all` - Stage all unstaged changes including untracked files
- `-m, --message` - Commit message
- `-i, --insert` - Insert between current branch and its child
- `-p, --patch` - Pick hunks to stage
- `-u, --update` - Stage updates to tracked files only
- `-v, --verbose` - Show diff in commit template
- `--ai` / `--no-ai` - AI-generate branch name and message

### gt modify

Amend current branch's commit or create new commit. Auto-restacks descendants.

**Flags:**

- `-a, --all` - Stage all changes
- `-c, --commit` - Create new commit instead of amending
- `-e, --edit` - Open editor for commit message
- `-m, --message` - New commit message
- `-p, --patch` - Pick hunks to stage
- `-u, --update` - Stage tracked file updates
- `--into` - Amend into specified downstack branch
- `--interactive-rebase` - Start git interactive rebase
- `--reset-author` - Set commit author to current user

### gt absorb

Amend staged changes to relevant commits in current stack.

**Flags:**

- `-a, --all` - Stage all unstaged changes (not untracked)
- `-d, --dry-run` - Print what would happen
- `-f, --force` - Skip confirmation
- `-p, --patch` - Pick hunks to stage

### gt squash

Squash all commits in current branch into single commit.

**Flags:**

- `-m, --message` - Commit message
- `--edit` - Modify existing message
- `-n, --no-edit` - Keep existing message

### gt fold

Fold branch's changes into parent, restack descendants.

**Flags:**

- `-k, --keep` - Keep current branch name instead of parent's

### gt split

Split current branch into multiple branches.

**Flags:**

- `-c, --commit, --by-commit` - Split by commit history
- `-h, --hunk, --by-hunk` - Split by hunk interactively
- `-f, --file, --by-file` - Split files matching pathspecs

## Submitting PRs

### gt submit

Push branches and create/update PRs on GitHub.

**Flags:**

- `-s, --stack` - Include descendant branches
- `-d, --draft` - Create PRs as drafts
- `-p, --publish` - Publish draft PRs
- `-e, --edit` / `-n, --no-edit` - Edit/skip PR metadata
- `--edit-title` / `--no-edit-title` - Edit/skip title
- `--edit-description` / `--no-edit-description` - Edit/skip description
- `-r, --reviewers` - Set reviewers (comma-separated or prompt)
- `-t, --team-reviewers` - Team slugs for review
- `-m, --merge-when-ready` - Auto-merge when requirements met
- `-c, --confirm` - Confirm before submitting
- `--dry-run` - Report what would happen
- `-f, --force` - Force push (vs --force-with-lease)
- `-u, --update-only` - Only update existing PRs
- `-v, --view` - Open PR in browser after
- `-w, --web` - Edit metadata in browser
- `--cli` - Edit metadata via CLI
- `--ai` / `--no-ai` - AI-generate title/description
- `--comment` - Add comment to PR
- `--restack` - Restack before submitting
- `--rerequest-review` - Rerequest from current reviewers
- `--always` - Push even if unchanged
- `--branch` - Run from specified branch
- `--target-trunk` - PR target trunk

### gt merge

Merge PRs from trunk to current branch via Graphite.

**Flags:**

- `-c, --confirm` - Confirm before merging
- `--dry-run` - Report what would merge

## Navigation

### gt checkout [branch]

Switch to branch. Interactive selector if no branch provided.

**Flags:**

- `-a, --all` - Show all trunks in selection
- `-u, --show-untracked` - Include untracked branches
- `-s, --stack` - Only show current stack
- `-t, --trunk` - Checkout trunk

### gt up [steps]

Switch to child of current branch.

**Flags:**

- `-n, --steps` - Levels to traverse
- `--to` - Target branch to navigate toward

### gt down [steps]

Switch to parent of current branch.

**Flags:**

- `-n, --steps` - Levels to traverse

### gt top

Switch to tip of current stack. Prompts if ambiguous.

### gt bottom

Switch to branch closest to trunk in current stack.

## Stack Management

### gt restack

Ensure each branch has parent in Git history, rebasing if needed.

**Flags:**

- `--branch` - Run from specified branch
- `--downstack` - Only restack branch and ancestors
- `--upstack` - Only restack branch and descendants
- `--only` - Only restack this branch

### gt move

Rebase current branch onto target, restack descendants.

**Flags:**

- `-o, --onto` - Target branch
- `--source` - Branch to move (default: current)
- `-a, --all` - Show all trunks in selection

### gt reorder

Reorder branches between trunk and current via editor.

## Syncing

### gt sync

Sync all branches with remote, clean merged/closed PRs, restack.

**Flags:**

- `-a, --all` - Sync across all trunks
- `-f, --force` - Skip confirmations
- `--restack` / `--no-restack` - Restack after sync (default: true)

### gt get [branch]

Sync branches from trunk to specified branch/PR from remote.

**Flags:**

- `-d, --downstack` - Don't sync upstack branches
- `-f, --force` - Overwrite with remote
- `--restack` / `--no-restack` - Restack after (default: true)
- `-U, --unfrozen` - Checkout as unfrozen

## Branch Operations

### gt delete [name]

Delete branch and Graphite metadata. Children restack to parent.

**Flags:**

- `-f, --force` - Delete even if not merged/closed
- `-c, --close` - Close associated PR on GitHub
- `--downstack` - Also delete ancestors
- `--upstack` - Also delete children

### gt rename [name]

Rename branch. Removes PR association.

**Flags:**

- `-f, --force` - Allow rename with open PR

### gt track [branch]

Start tracking branch with Graphite by selecting parent.

**Flags:**

- `-f, --force` - Use most recent tracked ancestor as parent
- `-p, --parent` - Specify parent branch

### gt untrack [branch]

Stop tracking branch. Children also untracked.

**Flags:**

- `-f, --force` - Skip confirmation

### gt pop

Delete current branch but keep working tree state.

### gt freeze [branch]

Freeze branch and downstack - prevents local modifications.

### gt unfreeze [branch]

Unfreeze branch and upstack.

## Information

### gt log [command]

Show stacks. Forms: `gt log`, `gt log short`, `gt log long`.

**Flags:**

- `-a, --all` - Show all trunks
- `-r, --reverse` - Print upside down
- `-u, --show-untracked` - Include untracked
- `-s, --stack` - Only current stack
- `-n, --steps` - Levels to show (implies --stack)
- `--classic` - Old style

### gt info [branch]

Display branch information.

**Flags:**

- `-b, --body` - Show PR body
- `-d, --diff` - Show diff vs parent
- `-p, --patch` - Show commit changes
- `-s, --stat` - Show diffstat

### gt parent / gt children / gt trunk

Show parent, children, or trunk of current branch.

`gt trunk` flags:

- `--add` - Add trunk
- `-a, --all` - Show all trunks

### gt pr [branch]

Open PR page for branch or PR number.

**Flags:**

- `--stack` - Open stack page

## Conflict Resolution

### gt continue

Continue command halted by rebase conflict.

**Flags:**

- `-a, --all` - Stage all changes first

### gt abort

Abort current command halted by conflict.

**Flags:**

- `-f, --force` - Skip confirmation

### gt undo

Undo most recent Graphite mutations.

**Flags:**

- `-f, --force` - Skip confirmation

## Setup

### gt init

Initialize Graphite by selecting trunk branch.

**Flags:**

- `--trunk` - Trunk branch name
- `--reset` - Untrack all branches

### gt auth

Add auth token for GitHub.

**Flags:**

- `-t, --token` - Auth token from https://app.graphite.com/activate

### gt config

Configure Graphite CLI (interactive).

### gt upgrade

Update CLI to latest stable version.

## Git Passthroughs

These pass arguments directly to git:

- `gt add [args..]`
- `gt cherry-pick [args..]`
- `gt rebase [args..]`
- `gt reset [args..]`
- `gt restore [args..]`

### gt revert [sha]

Create branch reverting a trunk commit.

**Flags:**

- `-e, --edit` - Edit commit message