> ## Documentation Index > Fetch the complete documentation index at: https://graphite-58cc94ce.mintlify.site/docs/llms.txt > Use this file to discover all available pages before exploring further. # Develop 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. 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: * **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 feature for stacks](/merge-pull-requests) will merge down to the correct trunk branch. [Merge When Ready](/merge-when-ready) is only supported for merges into the default branch of your repo. Make sure you are enabling Merge When Ready only for PRs that you intend to merge into the default branch. The guide below shows you how to use Graphite for such projects. ## Prerequisites Your CLI version should be >= `1.4.0`. If you are on a lower version, [update your CLI version](/update-cli) to get the latest first-class support for multitrunk workflows. You should be familiar with how to: * [Create branches in a stack](/create-stack) * [Create and submit pull requests](https://graphite.com/create-submit-prs) Graphite treats each configured trunk independently and can only merge stacked PRs into their trunk. Performing trunk-to-trunk merges, such as updating a long-lived feature trunk with changes from a main trunk or vice-versa, is outside Graphite's scope and users can continue using their own `git` or CI workflow to handle this without conflicting with Graphite. ## Creating PRs off different trunks The trunk branch is the root of your stack that you open PRs against and eventually merge into. When you first initialize the CLI in a repo, Graphite will ask you to select a trunk branch. In the following tree, `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. ```bash Terminal theme={null} ◯ bug-fix │ ◯ feature1-frontend │ ◯ feature1-backend ◉─┘ main ``` In order to create a PR off a different trunk branch, you need to configure the branch you want to base off of as another trunk. Then you can check out that other trunk branch and create new branches off it. When you submit PRs for the branches based off other trunks, they will be based off these other trunks. The Graphite workflow is the same across trunks and Graphite now makes working with multiple trunks easy. For example, say you had a release branch `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: ```bash Terminal theme={null} ◯ bug-fix-1 │ ◯ feature1-frontend │ ◯ feature1-backend ◯─┘ main ◉ bug-fix-2 ◯ release-v10 ``` To switch back to working off of `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. ## Configuring trunks with the CLI When you first initialize the CLI in a repo, Graphite will ask you to select a trunk branch. ```bash Terminal theme={null} Welcome to Graphite! ? Select a trunk branch, which you base branches on - inferred trunk main (autocomplete or arrow keys) › ❯ main release-v10 green ``` After initial set up, you can then interactively configure what trunk branches you have configured via `gt config`: Run `gt config`: ```shell theme={null} gt config ``` Select `Repository-level settings` then `Trunk branches`: ```bash Terminal theme={null} ? What would you like to configure? › - Use arrow-keys. Return to submit. ❯ Repository-level settings Branch naming settings Submit settings Restack settings Default utilities Tips Yubikey reminders Exit ``` ```bash Terminal theme={null} ? Repo-level configuration › - Use arrow-keys. Return to submit. ❯ Trunk branches PR Templates Remote repository Back Exit ``` See your currently configured trunk branches, and the different options for configuring trunk branches: ```bash Terminal theme={null} ? Configured trunks: main release-v10 › - Use arrow-keys. Return to submit. ❯ Add additional trunk branch Remove configured trunk Configure a target trunk to open PRs against Back Exit ``` ### Adding an additional trunk branch From the interactive menu, select `Add additional trunk branch`: ```bash Terminal theme={null} ? Configured trunks: main release-v10 › - Use arrow-keys. Return to submit. ❯ Add additional trunk branch Remove configured trunk Configure a target trunk to open PRs against Back Exit ``` Select the branch you want to configure as a trunk: ```bash Terminal theme={null} ? Select a trunk branch, which you base branches on (autocomplete or arrow keys) › main develop ❯ release-v10 ``` You can also add an additional trunk branch non-interactively by using the `--add` flag with the [gt trunk](/command-reference#gt-trunk) command: ```bash Terminal theme={null} gt trunk --add ``` ### Removing a configured trunk branch **Note that removing a configured trunk may un-track all branches based locally on this trunk.** From the interactive menu, select `Remove configured trunk`: ```bash Terminal theme={null} ? Configured trunks: main release-v10 › - Use arrow-keys. Return to submit. Add additional trunk branch ❯ Remove configured trunk Configure a target trunk to open PRs against Back Exit ``` Select the configured trunk you would like to remove: ```bash Terminal theme={null} ? Which configured trunk would you like to remove? › ❯ main deploys ``` ### \[Optional] Configuring a target trunk to open PRs against **This is a not a common workflow and usually only used in workflows where you work off a branch locally (i.e. \*\***`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`: ```bash Terminal theme={null} ? Configured trunks: main release-v10 › - Use arrow-keys. Return to submit. Add additional trunk branch Remove configured trunk ❯ Configure a target trunk to open PRs against Back Exit ``` Select the local trunk you would like to set a target trunk for: ```bash Terminal theme={null} WARNING: You are about to configure Graphite to open PRs against a different remote branch than the one you are based on locally. WARNING: This is an uncommon workflow since most users develop locally based off the same branch they are merging PRs into. WARNING: This workflow is only recommended if your local branch is a descendant of the remote target. ? Which configured trunk would you like to set a target trunk for? › ❯ green release-v10 ``` Select the remote branch you would like to open PRs against on remote (by default, Graphite opens PRs against the same trunk you have set locally): ```bash Terminal theme={null} ? For branches based on main, which remote branch should Graphite open PRs against? By default, PRs will be opened against main on remote. › green (default) ❯ main release-v10 ``` ## Working with multiple trunks By default, all Graphite commands assume you are working off a single trunk. For times when you want to do things across multiple trunks, some commands have a `--all` flag to see/perform actions across all configured trunks. Everything else should work normally. ### Seeing your configured trunks `gt trunk` will print out the trunk your current branch is based off of: ```bash Terminal theme={null} > gt trunk main ``` `gt trunk --all` will print out all your configured trunks: ```bash Terminal theme={null} > gt trunk --all main deploys ``` ### Seeing your stacks across trunks `gt log [short]` will show you your stacks on your current trunk: ```bash Terminal theme={null} > gt log short ◉ bug-fix │ ◯ feature1-frontend │ ◯ feature1-backend ◯─┘ main ``` `gt log [short] --all` will show you all your stacks across all your configured trunks: ```bash Terminal theme={null} > gt log short --all ◉ bug-fix-1 │ ◯ feature1-frontend │ ◯ feature1-backend ◯─┘ main ◯ bug-fix-2 │ ◯ bug-fix-3 ◯─┘ release-v10 ``` ### Checking out branches across 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. ```bash Terminal theme={null} > gt checkout ? Checkout a branch (autocomplete or arrow keys) › ❯ ◯ bug-fix-1 │ ◯ feature1-frontend │ ◯ feature1-backend ◯─┘ main ``` Add the `--all` flag to see all branches across all configured trunks. `gt checkout --all`: ```bash Terminal theme={null} > gt checkout --all ? Checkout a branch (autocomplete or arrow keys) › ❯ ◯ bug-fix-1 │ ◯ feature1-frontend │ ◯ feature1-backend ◯─┘ main (trunk) ◯ bug-fix-2 │ ◯ bug-fix-3 ◯─┘ release-v10 (trunk) ``` ### Moving branches across trunks Similar to `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. ### Syncing branches across trunks By default, `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. ## Troubleshooting **PR is targeting the wrong trunk.** You can fix this by simply moving the branch onto the correct trunk: `gt move --onto {trunk}`. After that, you can submit your stack to reflect the changes remotely. Learn more about [tracking branches with gt track](/track-branches). ## Versions before 1.4.0 Before `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: ```bash Terminal theme={null} gt init --trunk ``` There was no real support for working on multiple trunks simultaneously.