
CLI
Command-line Interface
Graphite helps you throughout the whole development process - starting from the command line. Install the Graphite CLI to visualize, create, update, share, and submit stacks.
npm install -g @withgraphite/graphite-cli
brew install withgraphite/tap/graphite
How it works
The Graphite CLI is a thin wrapper over git. We simplify the process of trunk-based development and manage dependencies to enable stacking. Under the hood, we’re running git to create branches, commits, and metadata, which means you can still use git in your scripts, tooling, or whenever you feel like it.
01.
Creating your first stack
Stacks are just a chain of dependent PRs. To create a branch with Graphite, touch a file, and then run gt branch create
. To create a stack, do that again.
Note: Because Graphite just runs git under the hood, you can also create dependent PRs with git. Just run gt branch track
after so that Graphite can store the dependencies.
03.
Updating your stack
Once you’ve created your stack, you may need to make updates to branches that now have dependencies. Much like git, you:
- 1. Check out that branch
- 2. Update your files
- 3. Create a commit using
gt commit create
or amend your commit withgt commit amend
- 4. Graphite will automatically rebase any dependent PRs for you
Like creating a stack, you can also use git to update any PRs with dependencies. If you do so, just run gt stack restack
to automatically rebase any dependent PRs.
Rebase conflicts
If you run into rebase conflicts during a restack, graphite will drop you into the same merge conflict resolution state you might be familiar with from git. Once you have resolved your conflicts, just run gt continue
to intelligently apply that resolution to any dependent branches and continue with the rebase.
04.
Submitting your stack
To create, or update, Github PRs for everything in your stack, run gt stack submit
this will detect which branches need new PRs (and which ones have PRs which need to be updated), and ask you for a title and body for each PR (pulling in your preferred text editor and the PR body template).
Note: To submit, you need to have authenticated your CLI with Graphite.
05.
Syncing your repo
Once you merge a PR, you may want to delete the branch locally, or update any dependent branches to base off of trunk instead (which now includes your changes). To do so, just run gt repo sync
.
06.
Advanced: Editing your stack
Use commands like gt upstack onto
and gt downstack edit
to change the order of branches in your stack. If you’ve ever written a whole lot of code and want to split it into multiple branches, you can run gt branch split
.
07.
Advanced: Collaborating on your stack
If you ever want to checkout a teammate’s stack, just run gt downstack get
.