Learn the core Graphite command-line workflow for authoring stacked PRs.

graphite-workflow.md

Table of Contents

• Introduction
• Workflow
  • Creating a first pull request
  • Stacking a second pull request
  • Addressing reviewer feedback
  • Pulling the latest changes from main into your stack
  • Merging your stack

Introduction

Our gt CLI tool helps your core workflow in 2 key ways:

1. Simplifying git commands, especially some of the sharper edges like rebasing.
2. Enabling PR stacking, which can help you move faster and stay unblocked.

We think simplifying git and PR creation is compelling on its own! However, mixing in PR stacking to your workflow creates a powerful combination.

For an overview on PR stacking, visit stacking.dev.

Workflow

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 2,147,483,647 PRs.

Creating a first pull request

Creating a pull request with gt should feel similar to workflows you already do with GitHub:

# Checkout the main branch using gt checkout
gt checkout main

# Make changes with your editor
echo "new API method" > file.js

# Create a branch with a single commit using gt create
gt create -am "feat(api): Add new API method for fetching users"

# Push changes and create a new pull request with gt submit
gt submit

Stacking a second pull request

To stack more changes on top of an existing pull request:

# Make sure you checkout the first PR's branch
gt checkout your_first_pr_branch_name

# Make changes with your editor
echo "update frontend to use the API from PR 1" > \
  frontend/admin/UsersPage.tsx

# Create a second PR on top of the first one
gt create -am \
  "feat(frontend): Load and show a list of users in admin panel"

# Push the stack, which will also create a 2nd pull request
# on top of the first one
gt submit --stack

Once it's pushed, open the PR in Graphite:

gt pr

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.

Tip: Many commands have aliases – gt ss is an alias for gt stack --submit!

Addressing reviewer feedback

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_stack
echo "making some edits" > a_file_my_coworker_wants_changed.js

Next, run 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.js
git commit --amend --no-edit
gt 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 -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.

Pulling the latest changes from main into your stack

As you're developing new features, the main branch will eventually get ahead of your open branches.

To update all of your open stacks to have the latest changes from main, run:

gt sync

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.

Merging your stack

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 stack
gt top

# Open the PR in Graphite
gt pr

On the PR page, merge the stack by clicking the Merge button:

┌───────────┐
│   Merge   │
└───────────┘

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.