gt CLI tool helps your core workflow in 2 key ways:
Simplifying git commands, especially some of the sharper edges like rebasing.
Enabling PR stacking, which can help you move faster and stay unblocked.
We think simplifying
git and pull request creation is compelling on its own! However, adding pull request stacking to your workflow levels it up even further.
To read about the benefits of pull request stacking, visit stacking.dev.
This guide will walk you through the lifecycle of stacking: creating stacks, responding to reviewer feedback up and down the stack, pulling in new changes from the main branch to open stacks, and finally merging.
Not all changes require stacks, but the same commands & concepts apply to a single PR as to a stack of 25 PRs.
The Graphite workflow can be broken down to the following steps:
Create a stack
Submit the stack
Merge the stack
Sync from trunk & clean up your merged branches locally
Creating a pull request with
gt should feel similar to workflows you already do with GitHub:
# Checkout the main branch using gt checkoutgt checkout main# Make changes with your editorecho "new code changes" >> file.js# Create a branch with a single commit# - the --all flag will stage any modified files# - a branch will be created from the given `--message`# - the commit will have the given `--message`# - the branch will be checked out for yougt create --all \--message "feat(api): Add new API method for fetching users"# Push changes to your remote and create a new pull requestgt submit# If you need to make any follow up changes to the PR, you can# amend the existing commit with gt modifyecho "some more changes" >> file.jsgt modify --all# Submit new changesgt submit
While you're waiting for a review on your first pull request, you can continue to build out changes by stacking a second pull request on top of the first.
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.
gt treats stacking as a first-class concept. Stacking new PRs, addressing reviewer feedback in any part of your stack, and making sure upstack branches stay in sync with changes downstack are all seamlessly handled for you by the core
To stack more changes on top of an existing pull request:
# Open an interactive branch picker:## - select the pull request you want to stack on top of# - press Enter## to check the branch out.gt checkout# Make changes with your editorecho "update frontend to use the API from PR 1" > \frontend/admin/UsersPage.tsx# Create a second PR on top of the first onegt create --all \--message "feat(frontend): Load and show a list of users"# Push the stack, which will also create a 2nd pull request# on top of the first onegt submit --stack
Visualize your new stack locally:
gt log short # or run `gt ls`
Now that it's pushed, open the PR in Graphite:
and assign reviewers using the UI.
If you prefer assigning a reviewer at the same time as submitting, run:
gt stack --submit --reviewers alice
to assign @alice as the reviewer on each PR in the stack.
You can repeat the process of checking out the top branch, making changes, and creating a new branch with
gt create to create larger and larger PR stacks.
It's likely that you'll be asked to make some changes to your stack as a result of code review. The
gt modify command will let you edit any branch in a stack, and automatically restack all the branches above it.
Example: You have a stack of 2 PRs, and your coworker asks you to make changes on the bottom-most PR.
First, checkout the bottom PR and address the changes in your editor:
gt checkout first_pr_in_the_stackecho "making some edits" > a_file_my_coworker_wants_changed.js
gt modify to amend the last commit in this branch and restack all the branches above it:
gt modify -a
An equivalent (but more manual) way to do this would be:
git add a_file_my_coworker_wants_changed.jsgit commit --amend --no-editgt restack # restack all the branches above
Now the first branch has the new changes from your PR feedback, and the second branch stacked on top is fully up to date with those changes as well.
If you prefer to make a 2nd explicit commit for your PR feedback changes, you can do that with
gt modify as well. Replace the
gt modify -a command with:
gt modify --commit \--all \--message "Responded to reviewer feedback"# OR shorthandgt modify -cam "Responded to reviewer feedback"
and a new commit will be created for you. All branches above the current branch will be restacked on top of this new commit.
As you're developing new features, the
main trunk branch will eventually get ahead of your open branches.
To update all of your open stacks with the latest changes from
This command will:
Pull the latest changes into main
Restack (rebase) all your open PRs on top of the new changes in main
Prompt you to delete any local merged/closed branches
If any of your stacks happen to have merge conflicts as a result of restacking on the new main, gt sync will prompt you to checkout those branches, and manually run
gt restack to fix any conflicts.
Once your stack has been reviewed and is passing CI, open the top of the stack in the Graphite UI:
# Checkout the top PR in the stackgt top# Open the PR in Graphitegt pr
On the PR page, merge the stack by clicking the Merge button.
To only merge the first part of a stack and leave the rest unmerged, navigate downstack on the PR page to the top-most PR you want to merge from, and press the Merge button from there.
Once you've merged your stack into
main (or whatever your trunk branch is), run
gt sync to get the latest changes in
main. In addition to fetching updates,
gt sync will:
Automatically detect any merged/closed branches and prompt you to delete them locally.
Rebases any branches/stacks you have locally onto the newest changes.
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.