Background gradient

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

OR

brew install withgraphite/tap/graphite

Learn more in our docs
> 
gt branch checkout main
> 
touch file1.txt
> 
gt branch create -a -m “First in a stack”
> 
touch file2.txt
> 
gt branch create -a -m Second file in a stack

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.

Learn more
> 
gt branch checkout main
Checked out main.
> 
touch file1.txt
> 
gt branch create -a -m “First in a stack”
[12-09-First_in_a_stack 01acd7f] First in a stack 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 file1.txt
> 
touch file2.txt
> 
gt branch create -a -m “Second file in a stack”
[12-09-Second_file_in_a_stack 038e209] Second file in a stack 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 file2.txt

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. 1. Check out that branch
  2. 2. Update your files
  3. 3. Create a commit using gt commit create or amend your commit with gt commit amend
  4. 4. Graphite will automatically rebase any dependent PRs for you
Learn more

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.

> 
gt branch checkout 12-09-First_in_a_stack
Checked out 12-09-First_in_a_stack.
> 
touch another_file.txt
> 
gt add --all
Command: "add" is not a Graphite command,but is supported by git. Passing command through to git... Running: "git add --all"
> 
gt commit create -m "Adding another file"
[12-09-First_in_a_stack dea00dc] Adding another file 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 another_file.txt Restacked 12-09-Second_file_in_a_stack on 12-09-First_in_a_stack.

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).

Learn moreSign up for a Graphite account

Note: To submit, you need to have authenticated your CLI with Graphite.

> 
gt stack submit
🥞 Validating that this Graphite stack is ready to submit... ✏️ Preparing to submit PRs for the following branches... ▸ 12-09-First_in_a_stack (Create) ✔ Title … First in a stack ✔ Body › Skip (paste template) ✔ Submit › Create Draft Pull Request ▸ 12-09-Second_file_in_a_stack (Create) ✔ Title … Second file in a stack ✔ Body › Skip (paste template) ✔ Submit › Create Draft Pull Request

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.

Learn more
> 
gt repo sync -r
🌲 Pulling main from remote... main is up to date. 🧹 Checking if any branches have been merged/closed and can be deleted... main does not need to be restacked. 12-09-First_in_a_stack does not need to be restacked on main. 12-09-Second_file_in_a_stack does not need to be restacked on 12-09-First_in_a_stack.

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.

Learn more
> 
gt downstack edit
Editing downstack...
> 
gt branch split
Splitting branch...

07.

Advanced: Collaborating on your stack

If you ever want to checkout a teammate’s stack, just run gt downstack get.

Learn moreSign up for a Graphite account
> 
gt downstack get <branch_name>
Pulling main from remote... main is up to date. <branch_name> is up to date.
> 
gt branch checkout main
Checked out main.
> 
touch file1.txt
> 
gt branch create -a -m “First in a stack”
[12-09-First_in_a_stack 01acd7f] First in a stack 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 file1.txt
> 
touch file2.txt
> 
gt branch create -a -m “Second file in a stack”
[12-09-Second_file_in_a_stack 038e209] Second file in a stack 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 file2.txt
> 
gt log
12-09-Second_file_in_a_stack (current) 67 seconds ago 038e209 - Second file in a stack 12-09-First_in_a_stack 3 minutes ago 01acd7f - First in a stack main 24 hours ago 14bea19 - fix: font page buy button nit
> 
gt branch checkout 12-09-First_in_a_stack
Checked out 12-09-First_in_a_stack.
> 
touch another_file.txt
> 
gt add --all
Command: "add" is not a Graphite command,but is supported by git. Passing command through to git... Running: "git add --all"
> 
gt commit create -m "Adding another file"
[12-09-First_in_a_stack dea00dc] Adding another file 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 another_file.txt Restacked 12-09-Second_file_in_a_stack on 12-09-First_in_a_stack.
> 
gt stack submit
🥞 Validating that this Graphite stack is ready to submit... ✏️ Preparing to submit PRs for the following branches... ▸ 12-09-First_in_a_stack (Create) ✔ Title … First in a stack ✔ Body › Skip (paste template) ✔ Submit › Create Draft Pull Request ▸ 12-09-Second_file_in_a_stack (Create) ✔ Title … Second file in a stack ✔ Body › Skip (paste template) ✔ Submit › Create Draft Pull Request
> 
gt repo sync -r
🌲 Pulling main from remote... main is up to date. 🧹 Checking if any branches have been merged/closed and can be deleted... main does not need to be restacked. 12-09-First_in_a_stack does not need to be restacked on main. 12-09-Second_file_in_a_stack does not need to be restacked on 12-09-First_in_a_stack.
> 
gt downstack edit
Editing downstack...
> 
gt branch split
Splitting branch...
> 
gt downstack get <branch_name>
Pulling main from remote... main is up to date. <branch_name> is up to date.
Ready to start stacking?
Install the CLI today