Developing on multiple trunks

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:

To switch trunks:

Run gt config:

$ gt config

Select Repository-level settings:

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

Select Trunk branch:

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

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

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

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 release-v10. After a few final changes, you run gt modify to update your branch, and gt submit to submit the PR for review.

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.