The Graphite workflow
Note
Now that you've set up your CLI & web dashboard, it's time to get familiar with the core Graphite development workflow.
Let's say you're starting to work on a new feature (i.e. adding stories to Instagram), which involves an API, server, and front-end changes...
Today, you'd probably create one large "stories" feature branch with changes across all 3 surfaces...
...but with stacked changes, you can break up your changes into smaller branches which are easier to review:
You would start by creating your first branch:
# check out your trunk branchgt branch checkout main# * build Stories API *# create a new branch off of main with your changes and add a commit in a single line:gt add -A # add all unstaged changes (same syntax as git add - note thatthis commant will pass through to native git)gt branch create feat-stories-API -m "Stories - API [1/3]"# alternatively, you could do this with a single line:gt branch create -a feat-stories-API -m "Stories - API [1/3]"# if you prefer to create an empty feature branch first and THEN commit your changes to it, you can do so (note that an empty commit will be created on the branch first, see below):gt branch create feat-stories-API# * build Stories API *gt commit create -m "Stories - API [1/3]"# * make a small change to the stories API *gt commit amend
Tip
If you don't pass in a branch name, gt branch create
will auto-generate a branch name from your commit message. You can configure a prefix for gt branch create
to add to all of your auto-generated branch names using gt user branch-prefix
.
Note that unlike a standard git workflow - where you create a new branch before working on your feature - with gt
we recommend doing the following:
Start by building your feature on an existing branch
Add your unstaged changes with
gt add
(note that this will pass through to native git)Create a new branch and commit simultaneously with
gt branch create -m "{your commit message}"
You can still create a branch before staging changes, but Graphite will automatically create an empty commit on the branch. (This was a requirement of our legacy data model and may change in a future version!)
Graphite keeps track of the parent branch so that it can always fix your stacks if something changes underneath.
# view your current stacks as tracked by Graphitegt log # (log view)gt log short # (compact view of just stacks)
You can then submit your branch for review when you're done with the API portion...
# submit your current stack to GitHub, creating or updating PRs for each branch as necessarygt stack submit# view your current stacksgt log
...and continue to work by creating more stacked changes as your first PR is being reviewed.
# * build Stories server *# create a new branch off of feat-stories-api and add a commitgt branch create -a feat-stories-server -m "Stories - server [2/3]"# * build Stories frontend *# create a new branch off of feat-stories-server and add a commitgt branch create -a feat-stories-frontend -m "Stories - frontend [3/3]"# view your current stacksgt log
After your PR is approved, it can be merged in through the native Graphite web app, or via GitHub.
Whenever you merge a PT into remote/main
, you can sync Graphite to make sure the parent branch info for your local repo stays up to date with the remote repo...
# pull in the latest trunk branch from remote, delete local branches which were merged in, and recursively rebase upstack branches which have not been mergedgt repo sync# view your current stacksgt log
...and then continue to work on your stacked changes without worrying about conflicts.
You can also submit multiple changes at a time for approval:
# navigate to the top of the stackgt branch checkout maingt branch up 2 # -> checks out the branch 2 levels upstack (in this case feat-stories-frontend)# submit the current branch and all downstack branches to GitHub for reviewgt stack submit# view your current stacksgt log
Whenever you push a stack of PRs to GitHub, Graphite automatically adds a comment to every PR in the stack to help your reviewers navigate between them:
Once all the PRs in your stack have been approved, you can merge them all into trunk by having Graphite do the work for you (recommended) or by replicating those steps yourself manually. [TODO: add hyperlinks here]
Graphite makes it easy to continue building without interruptions - just sync your repo, start working on your next feature, and then start a new stack by creating a branch.
# pull in the latest trunk branch from remote, delete local branches which were merged in, and recursively rebase upstack branches which have not been mergedgt repo syncgt branch checkout main# * work on update to stories *# create a new branch off of feat-stories-frontendgt branch create -a feat-stories-update -m "Stories - update"# view your current stacksgt log
Now that you have a sense of how to build using the stacked changes workflow with Graphite, feel free to explore our detailed documentation and start creating stacks of your own!