Live streamJoin us for "State of code review 2024" on July 18thRegister today
Background gradient
Icon

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.

brew install withgraphite/tap/graphite

Learn more in our docs
> 
gt checkout main
> 
touch file1.txt
> 
gt create -am "First in a stack"
> 
touch file2.txt
> 
gt create -am "Second in a stack"
> 
gt submit

00.

How it works

The Graphite CLI fully integrates with 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.

> 
gt --help
Graphite is a command line tool that makes working with stacked changes fast & intuitive...

01.

Creating your first stack

A stack is a series of dependent code changes. Graphite represents each change in a stack as a branch, which will be submitted as a pull request. To create a branch with Graphite, touch a file, and then run gt create. To create a stack, do that again.

> 
gt checkout main
Checked out main.
> 
touch file1.txt
> 
gt create -am "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 create -am "Second in a stack"
[12-09-Second_in_a_stack 038e209] Second 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 iterate on branches that now have dependencies. Graphite makes it painless to update your stacked changes by rebasing any dependent branches for you when you make changes:

  1. 1. Check out the branch to update
  2. 2. Update your files
  3. 3. Amend the commit on your branch with gt modify (or create a new commit with gt modify --commit).
  4. 4. Graphite will automatically rebase any dependent branches for you

Like creating a stack, you can also use Git to update any PRs with dependencies. If you do so, you can run gt 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 conflict resolution state you might be familiar with from Git. Once you have resolved your conflicts, run gt continue to intelligently apply that resolution to any dependent branches and continue with the rebase.

> 
gt 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 modify
[12-09-First_in_a_stack 01acd7f] First in a stack 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 file1.txt create mode 100644 another_file.txt Restacked 12-09-Second_in_a_stack on 12-09-First_in_a_stack.

04.

Submitting your stack

To create or update GitHub pull requests (PRs) for your stack, run gt 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 PR template.

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

> 
gt submit --stack
🥞 Validating that this Graphite stack is ready to submit... ✏️ Preparing to submit PRs for the following branches... ▸ 12-09-First_in_a_stack (Create) ▸ 12-09-Second_in_a_stack (Create) 📨 Pushing to remote and creating/updating PRs...

05.

Syncing your repo

Once you merge a PR, you can use gt sync to clean up the branch locally and update any dependent branches to depend on trunk (which now includes your changes).

> 
gt sync
🌲 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_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 move and gt reorder to change the order of branches in your stack. If you ever end up with a whole lot of code and want to split it into multiple branches, you can use gt split.

> 
gt checkout 12-09-Second_in_a_stack
Checked out 12-09-Second_in_a_stack.
> 
gt move --onto main
Restacked 12-09-Second_in_a_stack on main.

07.

Advanced: Collaborating on your stack

If you ever need to checkout a teammate’s stack, use gt get.

> 
gt get Coworkers_branch
Pulling main from remote... main is up to date. Coworkers_branch is up to date.
> 
gt --help
Graphite is a command line tool that makes working with stacked changes fast & intuitive...
> 
gt checkout main
Checked out main.
> 
touch file1.txt
> 
gt create -am "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 create -am "Second in a stack"
[12-09-Second_in_a_stack 038e209] Second in a stack 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 file2.txt
> 
gt log
12-09-Second_in_a_stack (current) 67 seconds ago 038e209 - Second 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 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 modify
[12-09-First_in_a_stack 01acd7f] First in a stack 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 file1.txt create mode 100644 another_file.txt Restacked 12-09-Second_in_a_stack on 12-09-First_in_a_stack.
> 
gt submit --stack
🥞 Validating that this Graphite stack is ready to submit... ✏️ Preparing to submit PRs for the following branches... ▸ 12-09-First_in_a_stack (Create) ▸ 12-09-Second_in_a_stack (Create) 📨 Pushing to remote and creating/updating PRs...
> 
gt sync
🌲 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_in_a_stack does not need to be restacked on 12-09-First_in_a_stack.
> 
gt checkout 12-09-Second_in_a_stack
Checked out 12-09-Second_in_a_stack.
> 
gt move --onto main
Restacked 12-09-Second_in_a_stack on main.
> 
gt get Coworkers_branch
Pulling main from remote... main is up to date. Coworkers_branch is up to date.
Ready to start stacking?