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.

Prerequisites

You should be familiar with how to:

• Create branches in a stack

• Create and submit pull requests

Switching trunks with the CLI

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
    Tips
    Yubikey reminders
❯   Repository-level settings
    Exit

Select Trunk branch:

? 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:

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

When to switch trunks

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.

Example 1: release branches

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.

Example 2: feature branches

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.

Benefits of specifying the correct trunk for a PR

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.

Troubleshooting

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.