Quick start

Graphite is a simple code authoring & review platform designed for engineers to write and review smaller pull requests, stay unblocked, and ship faster. This short guide walks you through the ideal Graphite workflow.

​

Step 0 - Install the CLI

Install the Graphite CLI using either brew or npm:

​

brew installation

brew install withgraphite/tap/graphite

​

npm installation

npm install -g @withgraphite/graphite-cli@stable

​

Step 1 - Understand the Graphite workflow

+The Graphite workflow consists of 5 main steps: + +1. Create a stack
+2. Submit a stack
+3. Address feedback
+4. Merge a stack
+5. Sync + clean up

Throughout this cycle of work, you should be syncing changes frequently with main so that you stay current, and avoid running into big merge conflicts.
Syncing (gt sync, read more below) is essentially a git pull that does some extra work under the hood to manage your dependencies, cleans up your local state, and more.

​

But first, what is a stack?

A stack is a sequence of pull requests, each building off of its parent. Stacks enable users to break up a large engineering task into a series of small, incremental code changes, each of which can be tested, reviewed, and merged independently. To read more about the benefits of stacking, check out https://stacking.dev.

To visualize your stacks locally, simply run gt log or gt log short. Here’s how you can interpret the output:

​

Step 2 - Create a stack

Creating a stack is simple: start by entering a git repository and ensuring you have the main branch checked out. After that, create some changes and run:

gt create --all --message "commit message"

You can continue to cycle through these commands to add more branches to your stack.

Note: the --all tag automatically stages all unstaged changes when creating a branch. You can drop this flag if you’d prefer to stage your changes manually — see all of the flags supported by gt create in the CLI command reference.

​

Step 3 - Submit a stack

When you’re ready to put your stack up for review, you can do so by running:

gt submit --stack

from any branch in your stack. This command will push changes to remote, as well as create or update pull requests for each of the branches in your stack.

​

Step 4 - Address feedback

After putting your stack up for review, you may need to make changes based on feedback from your reviewer(s). To do so, check out the desired branch and run:

gt modify

This command will automatically rebase any dependent changes or prompt you to resolve merge conflicts if applicable.

Note: By default, gt modify amends the last commit on the branch. To create a new commit, use gt modify --commit. See more flags for modify in the CLI command reference.

​

Step 5 - Merge a stack

While it’s possible to merge PRs created with Graphite through GitHub, we strongly recommend merging stacks of PRs from Graphite since you can merge all your PRs in the stack at once!
Graphite will handle all of the rebasing/merging for you.

To do so, navigate to the app.graphite.dev... links outputted by the CLI, navigate to the top of the stack (in this case, the dropdown next to the PR should say 3 of 3), and click the Merge 3 PRs button.

​

Step 6 - Sync + clean up

Once you’ve merged your stack into main (or whatever your base branch is), run:

gt sync

to get main’s latest changes. In addition to fetching updates, sync:

• Automatically detects any merged/closed branches and prompt you to delete them locally.
• Rebases any branches/stacks you have locally onto the newest changes.

​

Continuous sync with main

To make sure you’re always working on the most up-to-date version of your base branch, make sure you’re frequently running gt sync throughout your workflow.