Skip to content

Instantly share code, notes, and snippets.

@BrianHung

BrianHung/gt-cursorrule.md

Created May 29, 2025 17:19
Show Gist options
  • Save BrianHung/65e1ee8e6cc069553be0bc9e838caee9 to your computer and use it in GitHub Desktop.
Save BrianHung/65e1ee8e6cc069553be0bc9e838caee9 to your computer and use it in GitHub Desktop.
Download ZIP
cursorrule for gt (graphite cli)
Raw
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.)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment