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 branch
gt 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 that 
this 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:

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}"

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 Graphite
gt 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 necessary
gt stack submit

# view your current stacks
gt 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 commit
gt 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 commit 
gt branch create -a feat-stories-frontend -m "Stories - frontend [3/3]"

# view your current stacks
gt 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 merged
gt repo sync

# view your current stacks
gt 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 stack
gt branch checkout main
gt 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 review
gt stack submit

# view your current stacks
gt 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 merged
gt repo sync
gt branch checkout main

# * work on update to stories *

# create a new branch off of feat-stories-frontend
gt branch create -a feat-stories-update -m "Stories - update"

# view your current stacks
gt 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!