Git matched multiple remote tracking branches

Sometimes when I run a command like git checkout chore/fix-typo, I get an error message like fatal: ‘chore/fix-typo’ matched multiple (2) remote tracking branches.

hint: If you meant to check out a remote tracking branch on, e.g. 'origin',
hint: you can do so by fully qualifying the name with the --track option:
hint:
hint:     git checkout --track origin/<name>
hint:
hint: If you'd like to always have checkouts of an ambiguous <name> prefer
hint: one remote, e.g. the 'origin' remote, consider setting
hint: checkout.defaultRemote=origin in your config.
fatal: 'chore/fix-typo' matched multiple (2) remote tracking branches

The Immediate Fix

As described in the hint, we can repeat our command but add --track origin/ before our branch name.

So if we were trying to run git checkout chore/fix-typo, we would instead run

git checkout --track origin/chore/fix-typo

This tells Git to checkout chore/fix-typo from the origin remote and track the branch so git pull or git push knows which remote branch it is pulling from or pushing to.

The Long Term Solution

If we want to avoid this situation in the future, we can run this command once and it will update our Global Git Configuration file.

git config --global checkout.defaultRemote origin

This command tells Git that if there are multiple remotes to always assume origin is the remote we want to use when doing a git checkout. Running this command completes the step recommended by the hint in the error message

If you'd like to always have checkouts of an ambiguous <name> prefer
one remote, e.g. the 'origin' remote, consider setting
checkout.defaultRemote=origin in your config.

Why this Error Occurs

When you initially clone a repository, there is one remote that is used for fetch and push.

If you run git remote -v, you can see this in the output

origin  git@github.com:salcode/myrepo.git (fetch)
origin  git@github.com:salcode/myrepo.git (push)

Note: git pull does a git fetch behind the scenes

Additional remotes can be added by running git remote add or by using some third-party tools (as a PHP developer, I often see this from using Composer).

composer        git@github.com:salcode/myrepo.git (fetch)
composer        git@github.com:salcode/myrepo.git (push)
origin  git@github.com:salcode/myrepo.git (fetch)
origin  git@github.com:salcode/myrepo.git (push)

Even though these remotes point to the same URL, Git sees these as two separate remotes, composer and origin.

So when we run git checkout chore/fix-typo, Git doesn’t know if we want composer/chore/fix-typo or origin/chore/fix-typo (even though they are the same thing).

The Solution

Running the “Long Term Solution” line at the beginning of this article

git config --global checkout.defaultRemote origin

automatically adds the following to our Global Git Configuration file.

[checkout]
    defaultRemote = origin

This tells Git that when you have the situation where the branch exists on two remotes, use the origin remote.

We can still explicitly define which remote to use by running something like

git checkout --track composer/chore/fix-typo

but running git checkout chore/fix-typo will now default to using the origin remote and we won’t see the “matched multiple remote tracking branches” fatal error.

Sal Ferrarello (@salcode)

Sal is a PHP developer with a focus on the WordPress platform. He is a conference speaker with a background including Piano Player, Radio DJ, Magician/Juggler, Beach Photographer, and High School Math Teacher. Sal can be found professionally at WebDevStudios, where he works as a senior backend engineer.