Familiarizing yourself with gt
Welcome to Graphite! Once you've installed the CLI, it's time to start learning the core commands and workflow.
We'll start with the basics of creating a stack of changes, submitting the changes for review, addressing comments, and merging them. Later on in the guide, we'll get into other topics including reordering stacked branches and collaborating on stacks with your teammates.
Commands
Graphite's commands (for the most part) follow a noun-verb model, i.e. gt branch create
creates a branch. We'll go over most commands in the following pages. If you at any time need help remembering a command, how it works, or what the shortcuts are, we do our best to provide a multitude of ways to unblock yourself:
--help
options for every commandRun
gt --help
to see the list of top-level commands (mostly nouns)Run
gt <noun> --help
to see all options that can be passed to the commandRun
gt <command> --help
to see all options that can be passed to the command
The command reference page found at the end of this guide.
Tip
Graphite's CLI features a git passthrough - gt
will pass any unrecognized commands through to git
, so you can run commands like gt add
or gt status
, even though they aren't native commands in gt
.
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. Learn more here
.
Definitions
Stack: A series of git
branches that depend on each other. Starts at main
(or whatever your trunk branch may be called), and proceeds "upward" as dependent branches are stacked on. Commands within the "stack" noun operate on all ancestors and descendants of a branch.
Upstack: Branches further away from main
in a stack (more recent; descendants; recursive children). Commands within the "upstack" noun operate on a branch and descendants.
Downstack: Branches closer to main
in a stack (less recent; ancestors; recursive parents). Commands within the "downstack" noun operate on a branch and its ancestors.
If you're still a little confused about what these actually mean in practice, don't worry! Just keep reading and it'll all make sense soon enough.
More help
If you ever run into trouble figuring something out, or have a suggestion on how this documentation might be improved, please reach out in our community Slack channel.