cursorrule for gt (graphite cli)

gt-cursorrule.md

Guidelines

1. Default to gt. Substitute any suggested git command with the nearest gt command if available.
2. Keep stacks healthy. When a branch with children changes, rely on gt (e.g., gt modify, gt sync) to restack; avoid manual rebases unless unavoidable.
3. Avoid empty branches. Do not create an empty branch first. Add changes → gt create.
4. Show full commands in docs; aliases (gt m, gt ss) are acceptable in chat examples.
5. Teach the five‑step workflow (Create → Submit → Address Feedback → Merge → Sync).

---

Why PR Stacking & gt

• Smaller, review‑friendly PRs. Each branch/PR shows only its own change.
• Faster iteration. gt hides rebase/restack pain.
• Single mental model. One branch ≈ one commit.

---

🏃 Examples (workflow + snippets)

1  Create & Submit a PR

# on trunk
gt checkout main
# code …
gt create -am "feat(api): add users endpoint"
gt submit      # draft PR

2  Stack Another PR While Waiting

gt checkout              # fuzzy‑pick base branch
# more code …
gt create -am "feat(ui): list users"
gt submit --stack        # pushes both PRs

3  Address Mid‑Stack Feedback

gt checkout users-endpoint   # select PR to edit
# edits …
gt modify -a                 # amend & auto‑restack
gt submit                    # update PR(s)

4  Keep Up with main

gt sync -f       # pull trunk, restack, delete merged branches

5  Merge the Stack

gt top && gt pr   # open top PR → click **Merge Stack**

🔎 Navigation Cheatsheet

Action	Command	Alias
View stack	gt log short	gt ls
Go up / down	gt up, gt down	gt u, gt d
Jump tip / base	gt top, gt bottom	gt t, gt b
Interactive checkout	gt checkout	gt co

---

📜 Complete Command Reference

(Each entry: command — one‑line purpose · arguments)

• abort — Abort a Graphite command paused by rebase conflict ·[-f|--force]
• absorb — Amend staged changes into the correct commits downstack ·[-a|--all] [-p|--patch] [-d|--dry-run] [-f|--force]
• add — Passthrough to git add.
• aliases — Edit or reset CLI aliases ·[--legacy] [--reset]
• auth — Store GitHub auth token ·[-t|--token <TOKEN>]
• bottom — Checkout branch closest to trunk in current stack.
• changelog — Show CLI changelog.
• checkout [branch] — Switch branch or open interactive picker ·[-a|--all] [-s|--stack] [-t|--trunk] [-u|--show-untracked]
• children — List children of current branch.
• completion — Shell‑completion setup.
• config — Configure Graphite CLI (trunk etc.).
• continue — Resume a halted Graphite command ·[-a|--all]
• create [name] — Stage + commit + branch in one step ·[-a] [-m|--message] [-p|--patch] [-i|--insert] [--ai|--no-ai] [-u|--update] [-v|--verbose]
• dash — Open Graphite dashboard.
• delete [name] — Delete branch & metadata ·[-f|--force]
• demo [name] — Run interactive CLI demo.
• docs — Open CLI docs.
• down [n] — Move to parent (optionally multiple levels) ·[-n|--steps]
• feedback [msg] — Send message to maintainers ·[-d|--with-debug-context]
• fish — fish‑shell completion.
• fold — Squash branch into parent and restack descendants ·[-k|--keep]
• get [branch] — Fetch a stack from remote ·[-d|--downstack] [-f|--force] [--restack/--no-restack]
• guide [title] — Read extended guides.
• info [branch] — Show PR/body/diff for branch ·[-b|--body] [-d|--diff] [-p|--patch] [-s|--stat]
• init — Initialise or change trunk ·[--trunk <name>] [--reset]
• interactive — Start Graphite Interactive (web UI) ·[--port] [--foreground] [--command] [--no-open] [--force] [--kill]
• log [long|short] — Visualise branch graph ·[-a] [-s] [-n <steps>] [-u|--show-untracked] [-r|--reverse] [--classic]
• merge — Merge PRs from trunk up to current via Graphite ·[-c|--confirm] [--dry-run]
• modify — Amend or add commit on current branch, restack descendants ·[-a] [-c|--commit] [-m|--message] [-p|--patch] [-u|--update] [-v|--verbose] [--interactive-rebase]
• move — Rebase current onto new parent ·[-o|--onto <branch>] [--source <branch>] [-a|--all]
• parent — Show parent branch.
• pop — Delete branch but keep worktree state.
• pr [branch] — Open PR or stack page ·[--stack]
• rebase [args…] — Passthrough to git rebase.
• rename [name] — Rename current branch ·[-f|--force]
• reorder — Re‑order branches between trunk and current.
• reset [args…] — Passthrough to git reset.
• restack — Ensure ancestry is correct, rebase if needed ·[--branch] [--downstack|--upstack|--only]
• restore [args…] — Passthrough to git restore.
• revert [sha] — Experimental git revert helper ·[-e|--edit]
• review — EXPERIMENTAL local review UI.
• split — Split current branch by commit/hunk ·[-c|--by-commit] [-h|--by-hunk]
• squash — Squash all commits in branch ·[-m|--message] [--edit|--no-edit]
• state — Show repo state summary.
• submit — Push/update PRs for stack ·[--stack] [-c|--confirm] [-d|--draft] [-m|--merge-when-ready] [-r|--reviewers] [--ai|--no-ai] [--cli] [--edit*] [--publish] [--always] [-f|--force] [-u|--update-only] [-v|--view] [-w|--web] [--restack/--no-restack]
• sync — Fast‑forward trunk, clean merged, restack open branches ·[-a|--all] [-f|--force] [--restack/--no-restack]
• top — Checkout tip of current stack.
• track [branch] — Start tracking branch with Graphite ·[-p|--parent <branch>] [-f|--force]
• trunk — Show or add trunk branches ·[--add] [-a|--all]
• undo — Undo last Graphite mutation ·[-f|--force]
• unlink [branch] — Detach PR from branch.
• untrack [branch] — Stop tracking branch ·[-f|--force]
• up [n] — Move to child branch ·[-n|--steps]

(For exhaustive flag definitions, consult @https://graphite.dev/docs/cli-overview or run gt <command> --help.)