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.
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.
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 createor amend your commit with
gt 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.
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.
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.
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.
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.
Advanced: Collaborating on your stack
If you ever want to checkout a teammate’s stack, just run
gt downstack get.