The Graphite workflow
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 work on a new feature (i.e. adding stories to Instagram), which involves 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:
1
# check out your trunk branch
2
gt branch checkout main
3
4
# * build Stories API *
5
6
# create a new branch off of main with your changes and add a commit in a single line:
7
gt add -A # add all unstaged change (same syntax as git add - note that this command will pass through to native git)
8
gt branch create feat-stories-API -m "Stories - API [1/3]"
9
10
# alternatively, you could do this with a single line:
11
gt branch create -a feat-stories-API -m "Stories - API [1/3]"
Copied!
Note that 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 - see the CLI command reference for more details.
Note that unlike a standard git workflow - where you create a new branch before working on your feature - with
gt you do the following:- 1.Start by building your feature on an existing branch
- 2.Add your unstaged changes with
gt add(note that this will pass through to native git) - 3.Create a new branch and commit simultaneously with
gt branch create -m "{your commit message}"
Graphite keeps track of the parent branch so that it can always fix your stacks if something changes underneath.
1
# view your current stacks as tracked by Graphite
2
gt log # (log view)
3
gt log short # (compact view of just stacks)
Copied!
You can then submit your branch for review when you’re done the API portion…
1
# submit your current stack to GitHub, creating or updating PRs for each branch as necessary
2
gt stack submit
3
4
# view your currrent stacks
5
gt log
Copied!
…and continue to work by creating more stacked changes as your first PR is being reviewed.
1
# * build Stories server *
2
3
# create a new branch off of feat-stories-api and add a commit
4
gt branch create -a feat-stories-server -m "Stories - server [2/3]"
5
6
# * build Stories frontend *
7
8
# create a new branch off of feat-stories-server and add a commit
9
gt branch create -a feat-stories-frontend -m "Stories - frontend [3/3]"
10
11
# view your currrent stacks
12
gt log
Copied!
After your PR is approved, it can be merged in.
1
# * merge in your changes on GitHub or the Graphite web dashboard [coming soon] *
Copied!
Whenever you merge a PR 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…1
# pull in the latest trunk branch from remote, delete local branches which were merged in, and recursively rebase upstack branches which have not been merged
2
gt repo sync
3
4
# view your current stacks
5
gt log
Copied!
…and then continue to work on your stacked changes without worrying about conflicts.
You can also submit multiple changes at a time for review and approval:
1
# navigate to the top of the stack
2
gt branch checkout main
3
gt branch next 2 # -> checks out the branch 2 levels upstack (in this case feat-stories-frontend)
4
5
# submit the current branch and all downstack branches to GitHub for review
6
gt stack submit
7
8
# view your current stacks
9
gt log
Copied!
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.
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.
1
# pull in the latest trunk branch from remote, delete local branches which were merged in, and recursively rebase upstack branches which have not been merged
2
gt repo sync
3
gt branch checkout main
4
5
# * work on update to stories *
6
7
# create a new branch off of feat-stories-server
8
gt branch create -a feat-stories-update -m "Stories - update"
9
10
# view your current stacks
11
gt log
Copied!
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!
Export as PDF
Copy link