Developing on multiple trunk branches
Learn how to develop against multiple trunk branches with the Graphite CLI.

Some codebases don't have a single trunk branch (e.g. all commits go to main), but rather multiple longer-lived trunk branches. The guide below shows you how to use Graphite for such projects.

You should be familiar with how to:

There's two ways to switch trunks: interactive via gt config, and non-interactive via gt init. Both are equivalent.

Run gt config:

shell
$ gt config

Select Repository-level settings:

Terminal
? What would you like to configure? › - Use arrow-keys. Return to submit.
Branch naming settings
Pull request description settings
Default utilities
Tips
Yubikey reminders
❯ Repository-level settings
Exit

Select Trunk branch:

Terminal
? Repo-level configuration › - Use arrow-keys. Return to submit.
❯ Trunk branch
PR Templates
Remote repository
Back
Exit

Finally, specify the trunk branch you'd like to start using:

Terminal
? Select a trunk branch, which you open pull requests against - inferred trunk main (autocomplete or arrow keys)
❯ main
experimental
release-v10

This is equivalent to gt config: there's no risks when running this multiple times in the same repo as you switch between branches.

shell
gt init --trunk <trunk-name>

Specify the trunk branch whenever you're working on a PR on a different trunk. In particular, when switching between branches targeting different trunks, be sure to update your trunk in Graphite.

Say you're developing against 2 trunks: main for a new feature, and release-v10 for a bug fix.

  1. When developing the new feature, you run gt checkout main and gt config to specify main as the trunk branch.

  2. After implementing the first part of your feature, you start a new stack using gt create and call it new-feature.

  3. You now need to fix a bug in release-v10, so you switch using gt checkout release-v10 and gt config to specify release-v10 as the trunk branch.

  4. After finishing the bug fix, you run gt create and gt submit to submit the fix for review.

  5. You come back to your feature branch by running gt checkout new-feature and gt config to specify trunk main. After a few final changes, you run gt modify to update your branch, and gt submit to submit the PR for review.

Say you're building a new feature: new-feature will be a long-lived branch forked off main, and periodically sync in changes from main.

  1. After creating the branch new-feature, run gt checkout main and gt config to specify new-feature as the trunk branch. You develop as usual off this branch.

  2. You want to pull in changes from main, so you run gt config to temporarily specify main as trunk for the purposes of syncing.

  3. You run gt sync to pull in changes from main.

  4. To continue development on your branch, you switch trunk back to new-feature using gt config.

Specifying the correct trunk for a PR gives you the following benefits:

  • Developing: the output of gt ls will be clearer, e.g. running gt ls on main will show stacks based on main.

  • Reviewing: requirements like CI status will be evaluated against the trunk branch's branch protection rules on Graphite's PR page. This is especially useful for upstack PR's, where Graphite evaluates requirements like CI against trunk.

  • Merging: Graphite's "merge all" feature for stacks will merge down to the correct trunk branch.

PR is targeting the wrong trunk. You can fix this by simply running gt checkout {branch}, then gt config to select the correct trunk, and gt track to update the PR. After that, you can submit your stack to reflect the changes remotely. Learn more about tracking branches with gt track.

Give your PR workflow
an upgrade today

Stack easier | Ship smaller | Review quicker

Or install our CLI.
Product Screenshot 1
Product Screenshot 2