CLI command reference

Search…
You can always access the full help docs for the Graphite CLI by running gt --help
Graphite commands are formatted as noun-verb combinations where the noun is the subject of the command (e.g. gt branch checkout).
These nouns include:
​commit​
​branch​
​stack​
​downstack​
​upstack​
​repo​
​log​
​user​
​feedback​
​auth​
At a glance, we find that the most commonly useful commands for users to know are:
Fetching Changes (e.g. git pull)
gt repo sync
Creating Changes
gt branch create
gt commit create
gt commit amend
Rebasing
gt stack fix
gt upstack onto
Submitting Changes
gt stack submit
gt downstack submit
gt upstack submit
Misc
gt log
gt feedback
commit
Where possible, prefer using commit commands to using their underlying git equivalents. Graphite's commit commands utilize Graphite's understanding of our stack to fix your stack after the commit creation/amend, minimizing merge conflicts.
All gt commit commands can also be accessed by the shortcut gt c.
A select subset of commands also have combined shortcuts, e.g. gt commit create as gt cc, noted below.
gt commit create ** or ** gt cc
Create a new commit and fix the upstack branches.
Options:
-a
--all
Stage all changes before committing.
-m <message>
--message <message>
The message for the new commit.
gt commit amend ** or ** gt ca
Amend the most recent commit and fix the upstack branches.
Options:
-a
--all
Stage all changes before committing.
-m <message>
--message <message>
The updated for the new commit.
-n
--no-edit
Don't modify the existing commit message.
branch
All gt branch commands can also be accessed by the shortcut gt b.
A select subset of commands also have combined shortcuts, e.g. gt branch checkout as gt bco, noted below.
gt branch create <name> ** or ** gt bc <name>
Create new stacked branch.
Options:
-a
--add-all
Stage all unstaged changes on the new branch.
-m <message>
--commit-message <message>
Commit staged changes on the new branch with this message.
gt branch checkout ** or ** gt bco
Interactively check out any branch in the repo.
Options:
--branch <name>
Check out the specified branch instead, i.e. gt branch checkout main.
gt branch up ** or ** gt bu
gt branch down ** or ** gt bd
Traverse upstack/downstack by one branch.
Options
-n <steps>
--steps <steps>
Traverse by n branches instead.
gt branch top
gt branch bottom
Traverse to the top/bottom of the stack. If there are multiple paths at any given point in the stack, prompts the user to select which path to take.
gt branch children
gt branch parent
List the child/parent branches of your current branch as tracked by Graphite.
gt branch submit
create PR / force push current branch
gt branch rename
Rename a branch and update its children's metadata.
gt branch delete
Delete a branch by name, by passing through to git branch -d
If the current branch is deleted, its parent will be checked out.
Options
-f
--force
Force delete the branch (i.e., git branch -D)
gt branch edit
Run a native git rebase --interactive over the commits on the current branch.
This command is intended for advanced Git users who want to make use of the commit structure within a branch while working with Graphite.
gt branch show
Run a native git log over the commits on the current branch.
Options
-p
--patch
Show diffs (i.e., git log -p)
gt branch pr-info
Fetch and display GitHub PR information for the current branch.
stack
All gt stack commands can also be accessed by the shortcut gt s.
A select subset of commands also have combined shortcuts, e.g. gt stack submit as gt ss, noted below.
gt stack fix ** or ** gt sf
Fix the stack to match Graphite's knowledge (metadata) of the stack or resets Graphite's stack knowledge to match the current stack DAG.
Options:
--rebase
rebase git branches to match Graphite's knowledge of the stack
--regen
reset Graphite's stack knowledge based on current DAG of git branches
gt stack validate
Validate that Graphite's stack metadata matches the current DAG of local git branches.
gt stack submit ** or ** gt ss
Push each branch in the stack to GitHub and open a PR for it into its parent. Prompt the user to input the relevant PR information (e.g. title, body).
Submit launches an editor to allow you to edit PR info; this editor is controlled by your shell's default $EDITOR environment variable.
Options:
--draft
--no-draft
Create or update PRs for the stack in/not in GitHub draft mode.
--no-edit
Skip editing PR info inline; by default, if --no-edit is set, the associated PRs will be opened as drafts.
--dry-run
Reports the PRs that would be submitted and terminates. No branches are pushed and no PRs are opened or updated.
--reviewers
Manually specifiy the reviewers for new PRs
gt stack test <command>
Checkout each branch in the stack iteratively, and see if a command succeeds.
downstack
Downstack commands operate on the current branch and all of its recursive ancestor branches in the stack (up to trunk).
All gt downstack commands can also be accessed by the shortcut gt ds.
gt downstack submit
gt downstack validate
These commands are equivalent to gt stack counterparts (with the same options), but operate only on the downstack (inclusive) branches in the stack.
gt downstack edit
Edit the order of branches in a stack, and resolve any merge conflicts that arise when doing so.
gt downstack sync
Sync a branch and its downstack from remote.
upstack
Upstack commands operate on the current branch and all of its recursive descendant branches in the stack.
All gt upstack commands can also be accessed by the shortcut gt us.
gt upstack submit
gt upstack validate
These commands are equivalent to gt stack counterparts (with the same options), but operate only on the upstack (inclusive) branches in the stack.
gt upstack onto <branch>
Rebase all upstack branches onto the latest commit (tip) of the target branch.
repo
All gt repo commands can also be accessed by the shortcut gt r.
gt repo init
Initialize/re-initialize Graphite in the current git repository. Default mode for this command is interactive and you will be prompted for specifying your trunk branch and branches to ignore.
Init configurations are stored in the .git/.graphite_repo_config file.
Options
--trunk
The name of your trunk branch.
--ignore-branches
A list of branches (or glob patterns) that Graphite should ignore when tracking your stacks (i.e. branches you never intend to merge into trunk).
gt repo ignored-branches
Specify glob patterns matching branch names for Graphite to ignore. Often branches that you never plan to create PRs and merge into trunk.
This configuration is stored in the .git/.graphite_repo_config file inside your repo directory.
Options
--add
Add a branch or glob pattern to be ignored by Graphite.
--remove
Remove a branch or glob pattern from being ignored by Graphite.
gt repo sync ** or ** gt rs
Sync with remote and delete branches in the stack which have been merged into stack trunk, rebasing any unmerged upstack changes, also offering to resubmit PRs with changed bases and repair dangling Graphite branches.
Options
--show-delete-progress
Show a rough estimate of progress through deleting branches. (This is commonly used by users running gt repo sync in a long-standing git repo with tens/hundreds of dead branches where Graphite has just been initialized.)
-f
--force
Skip prompting to delete feature branches that have been merged into trunk, and suggesting resubmission of branches whose PR bases differ locally from remote. Instead, Graphite will take the default actions. To override default options, use one of the additional flags like --no-delete or --no-resubmit
--no-pull
Skip the step where Graphite pulls from remote.
--no-delete
Skip the step where Graphite checks whether feature branches have been merged into trunk and suggests deleting them.
--no-resubmit
Skip the step where Graphite suggests resubmitting branches whose PR bases differ locally from remote (often because they've been since rebased locally).
--no-show-dangling
Skip the step where Graphite checks for dangling branches (i.e. without a tracked parent in Graphite). Dangling branches are often the cause of mysterious bugs in Graphite behavior.
gt repo fix
Search for and remediate common problems in your repo that slow Graphite down and/or cause bugs.
Commonly remediated problems include: stale branches, branches with unknown parents.
Options
--show-delete-progress
Show a rough estimate of progress through deleting branches. (This is commonly used by users running gt repo sync in a long-standing git repo with tens/hundreds of dead branches where Graphite has just been initialized.)
-f
--force
Skip prompting to delete feature branches that have been merged into trunk. Instead, Graphite will take the default actions (may include deleting already merged branches and setting branch parents).
gt repo max-branch-length
Print the setting value of gt repo max-branch-length. Graphite will track up to this many commits on a branch. e.g. If this is set to 50, Graphite can track branches up to 50 commits long.
Increasing this setting will increase the accuracy of Graphite in repos with branches with many commits, but may result in slower Graphite performance.
Options:
--set <max-branch-length>
Set the value of max-branch-length.
gt repo max-days-behind-trunk
Print the setting value of max-days-behind-trunk. Graphite will track branches up to max-days-behind-trunk days behind trunk.
This is often used in repos where users have a plethora of local branches behind trunk causing slow Graphite performance.
Options:
--set <max-days-behind-trunk>
Set the value of max-days-behind-trunk.
gt repo max-stacks-behind-trunk
Print the setting value of max-stacks-behind-trunk. Graphite will track the most recent max-stacks-behind-trunk number of stacks behind trunk.
Options:
--set <max-stacks-behind-trunk>
Set the value of max-stacks-behind-trunk.
gt repo name
Print Graphite's understanding of the current repo name. e.g. in 'screenplaydev/graphite-cli', this is 'graphite-cli'.
Options:
--set <name>
Add a manual override to Graphite's inferred repo name.
gt repo owner
Print Graphite's understanding of the current repo owner. e.g. in 'screenplaydev/graphite-cli', this is 'screenplaydev'.
Options:
--set <owner>
Add a manual override to Graphite's inferred repo owner.
gt repo trunk
Print Graphite's understanding of the trunk branch of the current repo. This trunk branch is used interally in Graphite as the base of all stacks.
Options:
--set <trunk>
Add a manual override to Graphite's inferred repo trunk.
gt repo remote
Print Graphite's understanding of the current repo remote. e.g. 'origin'
Options:
--set <origin>
Add a manual override to Graphite's inferred remote.
gt repo pr-templates
Lists Graphite's view of the repo's GitHub PR templates. These PR templates are in turn used to pre-populate the body content of a PR when a user runs a gt submit command.
log
All gt log commands can also be accessed by the shortcut gt l.
gt log
gt log short
gt log long
Print a visualization of the current repo's stacks in the command line.
Options:
-t
--on-trunk
Only print commits and branches on trunk.
-b
--behind-trunk
Only print commits and branches behind trunk.
user
gt user branch-prefix
Print the setting value of branch-prefix. Graphite will prepend this prefix to all auto-generated branch names (i.e. when you don't specify a branch name when calling gt branch create).
Options:
--set <branch-prefix>
Set the value of branch-prefix (string).
gt user tips
Print whether Graphite tips are enabled.
Options:
--enable
Enable tips.
--disable
Disable tips.
gt user experimental
Print whether experimental Graphite features are enabled.
Options:
--enable
Enable experimental features.
--disable
Disable experimental features.
gt user editor
Print the text editor to use with Graphite when writing PR descriptions.
Options:
--set <editor>
Set your preferred editor, i.e. gt user editor --set vim.
--unset
Unset the default editor for Graphite.
feedback
gt feedback
Post a string directly to the maintainers' Slack, where they can factor in your feedback, laugh at your jokes, cry at your insults, or test the bounds of Slack injection attacks.
Options:
--with-debug-context
Include a blob of JSON describing your repo's state to help with debugging. Run gt feedback state to see what's included.
auth
gt auth
Associate an auth token with your Graphite CLI. This token is used to associate your local CLI instance with your Graphite account, allowing us to create and update PRs on GitHub on your behalf. To obtain your CLI token, visit https://app.graphite.dev/activate.
Options:
--token
Auth token value to save.