gt
and 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 gt
.
Example of gt vs. git
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
title
so 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
git
:
terminal
- 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.
gt
:
terminal
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.
Fixup commits in gt
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 withgit
:
TERMINAL
gt
:
TERMINAL
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.Working asynchronously
The reasongt
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.
In git
, you now have three options:
-
Wait until
task_search
is merged intomain
, pullmain
, then create a new branchprofile_search
and repeat the earlier steps- This isn’t great because you now need to wait for reviews and merging before you can work on
profile_search
- This isn’t great because you now need to wait for reviews and merging before you can work on
-
Update
task_search
with all changes required to implementprofile_search
- This isn’t great because now you have to further pollute the
task_search
PR which was already large, and wait for reviews from new reviewers, and so on.
- This isn’t great because now you have to further pollute the
-
Create a new branch
profile_search
on top oftask_search
, and make changes to that.- This works well, until you need to change
task_search
, and run a rebase. Thegt
workflow handles this for you automatically.
- This works well, until you need to change
gt
, you can simply run:
terminal
Check pointing in gt
A common use case forgit commit
is to check point yourself in the process of development. An example commit history would look something like:
- Initialize boilerplate
- Fix copy paste bug in boilerplate
- Fill out functions in boilerplate
- …
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 gt split
.Syncing from remote, restacking, and resubmitting
While you’re working on a piece of code, there is a chance that someone else touches the same code onmain
, or someone makes changes that you want to use. In git
, to handle this you could do:
terminal
gt
, you would do the following instead:
terminal
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 dogt restack
. Sogt 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.