Introduction to the CLI

With the CLI installed, you can now learn more about the recommended workflow and terminology for the core commands.

Commands

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.

• The command reference has a list of all gt commands.

• You can see the full list of commands with gt --help or command-specific help with gt <command> --help

• Enabling shell completion allows you to quickly complete commands without having to remember exactly what they are.

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.