In this guide, you’ll learn some of the main differences between using
git, like fixup commits, working asynchronously, check pointing, syncing from remote, and restacking.
Once you learn more about
gt and how it interacts with
git, you can then re-integrate your previous
git workflow into
Imagine you’re an engineer at a company that builds task management software (for example, Asana, Linear, or JIRA) and you want to build the ability to search across all task titles.
Let’s say this project has four parts:
Add an index to the task table on
titleso you can search through this field quickly
Add a helper function to query this table given a search query and returning tasks that match:
searchTasks(string searchQuery) -> Task
Expose an endpoint on your webserver that allows the frontend to search for tasks
Query this endpoint and display results on the frontend
Here’s how this would look in
// Create new branch & check it out$ git branch task_search && git checkout task_search// Make index changes (~10 lines of code)$ git add --all && git commit --message 'add index for searching tasks'// Make helper function (~50 lines of code)$ git add --all && git commit --message 'add helper function to search tasks'// Make endpoint (~100 lines of code)$ git add --all && git commit --message 'add endpoint to search tasks'// Make UI (~200 lines of code)$ git add --all && git commit --message 'addtUI to display searched tasks'// Push changes to remote$ git push origin task_search
Now you have a branch that implements search end to end. Next you want to get this reviewed by your teammates before it gets merged. There are a couple important issues here:
This is a large PR! It has many lines of code changes for someone to review.
The folks who own the UI are different from the folks who own the task table. You need multiple people on different teams to review your PR.
Here’s how this would look in
// Make index changes (~10 lines of code)$ gt create --all --message 'add index for searching tasks'// Make helper function (~50 lines of code)$ gt create --all --message 'add helper function to search tasks'// Make endpoint (~100 lines of code)$ gt create --all --message 'add endpoint to search tasks'// Make UI (~200 lines of code) using aliases$ gt create -a -m 'add UI to display searched tasks'// Submit changes to remote$ gt submit --stack
Now you have a stack that implements search end to end. A stack is made up of multiple branches stacked on top of each other.
Instead of creating a single PR to merge all these changes, Graphite creates four PRs for this stack (one per
gt create command above). You can get each PR reviewed by a person who is familiar with that particular change.
This solves the two issues when using
git: each PR with
gt is small (and easier to review), and you can get reviews from different people for different parts of your change depending on their expertise.
Continuing with the example above, let’s say you receive some comments about performance, related to the second part of your change “add helper function to search tasks”. You want to only search tasks within the last year—tasks older than that are out of scope for your search prototype.
How this looks with
// Make changes to limit the helper function's search scope to ~1 year$ git add --all // stage changes$ git commit --fixup=<commit hash of add helper function to search tasks> // Make the fixup commit$ git rebase --interactive --autosquash=<commit hash of add helper function to search tasks>~1 // Merge fixup commit into previous commit
How this looks with
$ gt checkout 'add helper function to search tasks'// Make changes to limit the helper function's search scope to ~1 year$ gt modify --all // Stage & amend these changes into "add helper function to search tasks"// Push stack to remote$ gt submit --stack
If you make changes lower down the stack, it is important to run
gt submit --stack versus just
gt submit because changes up the stack will not receive the new updates otherwise. This will result in the PR diff on the UI to not match what you see locally through
git show or
gt info --diff for any upstack PRs.
gt is so powerful is because it enables working asynchronously. Because each branch in the stack is independent, you can keep building on top of the existing changes without worrying about growing the size of your PR and making things a worse experience for reviewers.
Let’s say you’re waiting on your above PR(s) to be reviewed, when a colleague has a great idea that rather than just allowing people to search for tasks, you should also allow them to search for user profiles in the same UI.
git, you now have three options:
task_searchis merged into
main, then create a new branch
profile_searchand repeat the earlier steps
This isn’t great because you now need to wait for reviews and merging before you can work on
task_searchwith all changes required to implement
This isn’t great because now you have to further pollute the
task_searchPR which was already large, and wait for reviews from new reviewers, and so on.
Create a new branch
profile_searchon top of
task_search, and make changes to that.
This works well, until you need to change
task_search, and run a rebase. The
gtworkflow handles this for you automatically.
gt, you can simply run:
$ gt checkout 'add UI to display searched tasks'// Make changes to implement profile search$ gt create --all --message 'implement profile search'$ gt submit --stack
Now, implementing profile search is built on top of “add UI to display searched tasks”, but it creates a new PR that is independent of all the changes below it. You can keep building on top of this stack, while all PRs lower down the stack (”downstack”) are independent of these changes up the stack (”upstack”).
A common use case for
git commit is to check point yourself in the process of development. An example commit history would look something like:
Fix copy paste bug in boilerplate
Fill out functions in boilerplate
If you want to do something similar in
gt, just use
gt create every time you would
git commit. However, it is important to not
gt submit the entire stack until some organization is done, otherwise each of your intermediate check points will create PRs, making for a really poor review experience for your reviewers. Instead, once you have your changes in a good place, use
gt fold to fold a child branch into its parent. This will allow you to create checkpoints without submitting PRs for each checkpoint.
Run into any issues with
gt fold? You can always split it back into separate branches with
While you're working on a piece of code, there is a chance that someone else touches the same code on
main, or someone makes changes that you want to use. In
git, to handle this you could do:
$ git checkout main$ git pull$ git checkout <my new branch>$ git merge main
gt, you would do the following instead:
$ gt sync$ gt checkout <my new branch>$ gt restack // This will rebase your stack onto main
Let’s assume you have a stack of PR#1 → PR#2 → PR#3.
gt restack tells Graphite to check if any rebases need to happen in order to correct your dependency list. For example, let's say you make a change lower down in the stack, in PR #1. PR #3 doesn't know about this until you do
gt restack. So
gt restack is telling Graphite that you have made changes on a PR that could affect its children—to check the children for any conflicts, and perform a rebase if it finds them.