Learn how to develop against multiple trunk branches with the Graphite CLI.
main
), but rather multiple longer-lived trunk branches. Some reasons for this workflow may be release/deploy branches, long-lived feature branches, or staging branches. In these setups, creating branches and PRs off the correct trunk branch is critical for many reasons:
gt ls
will be clearer, e.g. running gt ls
on main
will show stacks based on main
.
1.4.0
. If you are on a lower version, update your CLI version to get the latest first-class support for multitrunk workflows.
You should be familiar with how to:
main
is the trunk and all the stacks are based off it. Each branch has a single dependency so each stack can only have a single trunk.
release-v10
that you needed to merge a bug fix into. You would first need to add release-v10
as a trunk branch. Then you can checkout the new trunk with gt checkout release-v10
. Once you’ve implemented your fix, you can use gt create
to create a branch for it in the same way as any other branch. You can then submit a PR for the bug fix which will open a PR against the trunk release-v10
. Your state will now look like the following:
main
, simply checkout main
again with gt checkout main
. Graphite supports easily switching between branches, even across trunks.
The next sections go into detail about how to add additional trunks and work with multiple trunks.
gt config
:
Run gt config
:
Repository-level settings
then Trunk branches
:
Add additional trunk branch
:
Remove configured trunk
:
green
**) that is strictly a descendant of the branch they merge into (i.e. **main
**). Targeting a different branch on remote than the one you have locally can otherwise have unknown consequences in the Graphite CLI.
By using this setup, you are choosing to open PRs against a different trunk than the one you work on locally. This means that you can base your branches off green
locally and have all PRs submitted through Graphite open PRs against another branch, main
.
From the interactive menu, select Configure a target trunk to open PRs against
:
--all
flag to see/perform actions across all configured trunks. Everything else should work normally.
gt trunk
will print out the trunk your current branch is based off of:
gt trunk --all
will print out all your configured trunks:
gt log [short]
will show you your stacks on your current trunk:
gt log [short] --all
will show you all your stacks across all your configured trunks:
gt checkout {branch_name}
will work with any Graphite tracked branch, regardless of the trunk it is based off of.
In the interactive selector, gt checkout
will by-default only show you options based off your current trunk.
--all
flag to see all branches across all configured trunks.
gt checkout --all
:
checkout
, gt move --onto {branch_name}
will work with any Graphite tracked branch, regardless of the trunk it is based off of. Add the --all
flag to see all branches across all configured trunks.
gt sync
will only update the trunk you are currently based off of and sync branches based off this current trunk. To update all your trunks and sync branches based off all your trunks at once, pass the --all
flag.
gt move --onto {trunk}
. After that, you can submit your stack to reflect the changes remotely. Learn more about tracking branches with gt track.
1.4.0
, Graphite only supported working off a single trunk at a time. So to switch trunk branches, you had to re-initialize the CLI with a different trunk every time you needed to switch which trunk you were working off of: