Graphite

Common aliases:

• gt ls = gt log short
• gt ll = gt log long
• gt sp = gt split
• gt ss = gt submit --stack

Core Workflow

1. Make your code changes.
2. Stage the relevant files with git add or gt add.
3. Create the stacked branch with gt create [name].
4. Use gt modify, gt absorb, gt split, or gt squash to shape the branch.
5. Restack with gt restack if parents or ancestry changed.
6. Use gt sync when you need to pull trunk updates and clean up merged branches.
7. Submit with gt submit, or gt submit --stack if you want descendants included.

Branch Creation And Editing

Create A Branch

git add <files>
gt create branch-name

If no branch name is provided, Graphite can generate one from the commit message.

Modify The Current Branch

git add <files>
gt modify -m "updated commit message"

Use -c, --commit to create a new commit instead of amending the current one, -a, --all to stage everything, and --into to amend staged changes into a downstack branch.

Absorb Staged Changes

Use gt absorb when staged hunks should be moved into earlier commits in the current stack.

Split Or Squash

• gt split breaks one branch into multiple branches by commit, hunk, or file. Use --by-commit, --by-hunk, or --by-file <pathspec>.
• gt squash combines the current branch into a single commit and restacks descendants.

Stack Navigation

gt up
gt down
gt top
gt bottom
gt checkout
gt parent
gt children
gt trunk

Use gt log short or gt ls to inspect the stack layout, and gt log long or gt ll for the commit graph.

Tracking And Reparenting

If a branch is untracked, start tracking it with gt track [branch] -p <parent>.

gt track -p main
gt restack

Use gt untrack [branch] to stop tracking a branch, and gt unlink [branch] to remove the PR association without deleting the branch. If Graphite metadata is corrupted, gt track [branch] can re-establish parent relationships.

For branch moves:

gt move --onto main

Use gt reorder when you want to rearrange branches between trunk and the current branch.

Submission

Submit The Stack

gt submit

Use gt submit --stack when you want to submit descendants of the current branch too.

Useful submit flags include:

• --ai
• --always
• --branch
• --draft
• --edit
• --publish
• --update-only
• --restack
• --cli
• --web
• --no-edit
• --no-edit-title
• --no-edit-description

Open PR Pages

gt pr
gt pr --stack

gt pr opens the current branch PR. gt pr --stack opens the stack page.

Deleting And Folding

Delete A Branch

gt delete [name] is local-only. It deletes the branch and restacks any children onto the parent branch. If the branch has an open PR, close it separately or use --close. Use --upstack or --downstack when you want to delete related branches too.

gt pop deletes the current branch but keeps the files in the working tree.

Fold A Branch

gt fold folds a branch into its parent, updates descendants, and restacks locally. If the branch has an open PR, close it separately. Use -k, --keep if you want to keep the current branch name.

Configuration

• gt completion sets up shell completion.
• gt config opens Graphite CLI configuration.
• gt aliases edits command aliases.
• gt aliases --legacy adds the legacy alias preset.
• gt auth adds the auth token needed to create and update GitHub PRs.
• gt docs opens the built-in docs.
• gt upgrade updates the CLI to the latest stable version.

Troubleshooting

Practical Defaults

• Prefer small, atomic branches that can be submitted independently.
• Keep the stack rooted on the intended trunk before submitting.
• Prefer the current flat gt commands over legacy alias spellings when writing examples or docs.
• When you need the exact command list or flags, check gt docs or gt --help --all.