Git: 'refusing to merge unrelated histories' - How to Fix It

Git refuses to merge unrelated histories when the two branches you are combining share no common commit. That happens most often when you ran git init locally, started committing, and then tried to pull a remote that already had its own commits. The one-line fix is to allow it explicitly:

git pull origin main --allow-unrelated-histories

That flag tells Git "yes, I know these two histories never touched before, stitch them together anyway." The rest of this page explains why Git blocks this by default, when it is safe to override, and how to avoid the situation in the first place.

The exact error

When you try to pull or merge two trees that have no shared ancestor, Git stops with:

fatal: refusing to merge unrelated histories

No commit is created. Nothing is changed. Git just declines to do the merge until you confirm you really meant it.

Why does this happen?

Every Git merge looks for a common ancestor, a commit that exists in the history of both branches. The merge uses that ancestor as the baseline to work out what changed on each side. When there is no common ancestor at all, the two histories are "unrelated," and a merge would have to blindly combine two completely separate project trees.

The classic way to end up here:

mkdir my-project
cd my-project
git init
echo "# My Project" > README.md
git add README.md
git commit -m "Initial commit"

# Meanwhile, a repo already exists on GitHub with its own commits
git remote add origin git@github.com:you/my-project.git
git pull origin main

Your local repo has one root commit. The remote has a different root commit (maybe GitHub created it for you when you ticked "Add a README"). Those two roots are unrelated. Git sees two separate timelines and refuses to merge them without a clear go-ahead.

You can also hit it when:

• You re-initialized a repo with rm -rf .git && git init and then tried to pull the old remote.
• You squashed or rewrote history so aggressively (say, rewriting history with rebase or filter-repo) that the new history shares no commit with the remote.
• You are merging a branch that was imported from a completely different project.

The fix: --allow-unrelated-histories

The flag exists precisely for this case. Add it to your pull:

git pull origin main --allow-unrelated-histories

Or, if you prefer to fetch and merge in two steps (see git pull vs git fetch for why you might):

git fetch origin
git merge origin/main --allow-unrelated-histories

If you do this often enough to wonder whether to merge or rebase, my notes on choosing merge vs rebase when reconciling divergent branches lay out the trade-off. Git will now perform the merge. Because the two sides touch different files, you usually get a clean merge commit with everything from both histories. If both sides happen to have edited the same file (a common one is README.md), you get a normal merge conflict to resolve. My walkthrough on resolving merge conflicts covers exactly that.

If your branch is called master instead of main, swap the name:

git pull origin master --allow-unrelated-histories

Why was this allowed before, and then blocked?

Older Git versions merged unrelated histories silently. That turned out to be a foot-gun: people would accidentally point at the wrong remote, pull, and merge two unrelated projects into one mangled tree without any warning. Git 2.9 (June 2016) flipped the default to refuse the merge unless you opt in with --allow-unrelated-histories. So the error is not a bug. It is a guardrail asking "are you sure?" before it does something that is hard to undo.

When is it safe to use the flag?

The rule of thumb: if you can explain why the two histories are unrelated and you are happy to combine them, the flag is correct. If the error surprises you, treat it as a warning that you are pulling from somewhere unexpected. Run git remote -v to confirm the remote URL and git log --oneline on both sides to see what you are about to mash together.

How to avoid it entirely

The cleanest way to never see this error is to start from the remote instead of starting locally. If the remote repo already exists, clone it rather than git init-ing a new one, because a fresh git init creates a brand-new history with its own root commit:

git clone git@github.com:you/my-project.git
cd my-project
# now just add your files and commit

A clone shares the remote's history from the first commit, so there is nothing unrelated to merge later. My guide on starting work on an existing Git project walks through that flow end to end.

If you have already committed locally and then discovered the remote exists, and you do not care about your local commits, the simplest reset is to back up your files, re-clone, and copy them in:

# from outside the project folder
mv my-project my-project-backup
git clone git@github.com:you/my-project.git
cp -r my-project-backup/your-files my-project/

But if you want to keep both sets of commits, --allow-unrelated-histories is the right tool and there is nothing wrong with using it.

Related Git fixes

This error often shows up alongside other first-push hiccups when you are wiring a local repo to a new remote:

• Git: 'failed to push some refs' when the remote has commits you do not have locally.
• Git: 'src refspec main does not match any' when you push a branch name that does not exist yet.
• Git: 'remote origin already exists' when you add a remote that is already configured.
• Setting the upstream branch when your first push complains there is no tracking branch to push to.

If you are still finding your feet with Git generally, start at my Git for beginners guide, which links out to the whole series.

FAQ