Fix 'Cannot Rebase Onto Multiple Branches' error once and for all

A Guide to using git pull --rebase effectively

Using git pull --rebase as your default merge strategy offers several benefits, particularly in maintaining a clean and linear commit history, which can simplify collaboration and code review. However, users may occasionally encounter the error “Cannot rebase onto multiple branches”. This article explains why this happens and provides a solution to make git pull --rebase work seamlessly.

Benefits of git pull --rebase

1. Linear History: Rebasing applies your local commits on top of the upstream changes, creating a straight line of commits without unnecessary merge commits. This makes the project history easier to read and understand.

2. No Merge Commits: Regular merges create additional merge commits, which can clutter the commit history, especially if frequent pulls are necessary. Rebase avoids these extra commits.

3. Single Conflict Resolution: With rebase, you only resolve conflicts once. When merging, conflicts can arise multiple times if multiple merges happen, but with rebase, each commit is reapplied one at a time on top of the upstream changes, and conflicts are resolved in the context of the latest code.

To use rebasing by default, add this to your ~/.gitconfig:

[pull]
   rebase = true

This is equivalent to adding the --rebase flag to each pull. However, this approach occasionally fails with the error “Cannot rebase onto multiple branches”, which is quite irritating because running git pull a second time usually works. This error occurs because multiple branches are available, and Git doesn’t know which one to rebase onto, even if you’re on the master branch (as that’s the branch I pull from most frequently).

Solution: Specify the Branch to Rebase Onto

Instead of relying on keyboard shortcuts like Ctrl+r, you can configure Git to always pull from the specific branch by default. This ensures that git pull --rebase works as expected every time.

Add these parameters on a per-branch basis in your ~/.gitconfig file:

[branch "master"]
   remote = origin
   merge = refs/heads/master

This configuration applies only to the master branch. Use main if you prefer; just copy and paste the config for it.

Enjoyed?