If you haven't already, be sure to follow the instructions to install the Graphite CLI.

A brief introduction to the CLI

Graphite has four main workflow commands: gt create to create branches, gt submit to turn those branches into pull requests, gt modify to make changes to your branches, and gt sync to synchronize with your GitHub remote repository.

You can see a full list of commands by running gt --help or command-specific help with gt <command> --help in your command line. The command reference is also handy for looking up specific commands you might need.

Recommended tutorials

Create a stack

Learn how to create a stack of PRs with the Graphite CLI.

Visualize a stack

If you've already created a stack with Graphite, see what they look like.

Navigate a stack

Learn how to move between branches in a stack using the CLI.

More on the CLI

A note on git passthrough

Graphite's CLI features git passthrough. This means gt will pass any unrecognized commands through to git. For example, you can run commands like gt add or gt status successfully even though they aren't native commands in gt—and you'll see a message like this:

> gt add .
Passing command through to git...
Running: "git add ."

Having git passthrough helps to avoid confusion about when to use gt vs. git. You should be able to use gt for everything in your git workflow!

Other definitions

Diff

A diff is short for difference and is technically the term used to describe a program's ability to show the difference between two or more files. At some large companies, the term "diff" is synonymous with a PR.

For example: "I just put up a diff that updates the button to the latest designs."

Stack

A stack is a series of git branches that depend on each other. It starts at main (or whatever your trunk branch may be called), and proceeds "upward" as dependent branches are stacked on. Commands with the stack parent command operate on all ancestors and descendants of a branch.

Trunk

In trunk-based development, the trunk is the central branch to which all developers send their code changes (many times it is main). There are many Graphite commands that accept --trunk flags to operate on or in reference to the trunk branch of the repository.

Mergeability

This is a pull request's calculated ability to be merged into its parent. This usually implies that it's passing CI, has been approved, has no merge conflicts, and satisfies any other branch protection rules on the parent branch.

Upstack

This refers to branches further away from main in a stack (more recent; descendants; recursive children).

Downstack

Branches closer to main in a stack (less recent; ancestors; recursive parents).

Restack

Whenever new changes are pushed to the trunk branch of a repository, restacking is the operation that applies those changes throughout any branches that are descendants of (or based on top of) the trunk branch. Often, restacking branches involves resolving merge conflicts and is performed right after syncing from a remote repository.

Command alias

Some gt commands have an "alias," or shortened form. Graphite also allows you to configure your own aliases for commands, to fit your workflow best.