Git

Git "Fatal: Refusing to Merge Unrelated Histories"

This error means Git has detected that the two branches (or repositories) you're trying to merge don't share any common commit ancestry at all — as far as Git can tell, they're two completely separate histories, not two diverging versions of the same project.

The Problem

You try to pull or merge, and Git refuses outright:

fatal: refusing to merge unrelated histories

This is different from a normal merge conflict — Git isn't even attempting to compare the changes, because it can't find any shared starting point between the two histories to compare from.

Why It Happens

Git tracks history through commit ancestry — each commit points back to its parent. This error appears specifically when the two histories being merged have no common ancestor commit at all. The most common causes are:

  • You initialized a new local repository with git init and made commits, then tried to pull from an existing remote repository that has its own separate initial commit — two independently created histories with nothing in common
  • A repository was re-initialized from scratch at some point (deleted .git folder and reinitialized), creating a fresh history disconnected from what existed before
  • You're merging two genuinely separate projects that were developed independently and are now being combined for the first time
  • A shallow clone (--depth) doesn't have enough history to find the common ancestor, even though one technically exists further back

The Fix

First, confirm this is actually expected in your situation — if you genuinely expect these two histories to be related (for example, you cloned what should be the same project), investigate before forcing anything:

git log --oneline --all --graph

If you determine the two histories are unrelated but you legitimately want to combine them (a very common and valid scenario — for example, connecting a fresh local git init to an existing GitHub repository created through the GitHub web UI), allow the merge explicitly:

git pull origin main --allow-unrelated-histories

Git will then attempt a normal merge, comparing the file contents even without shared ancestry. You may get regular merge conflicts at this point if both sides have files with the same name and different content (a common case: both sides have their own README.md) — resolve those the normal way:

git status
# resolve conflicts manually
git add resolved-file.md
git commit

If the cause was a shallow clone missing history rather than genuinely unrelated repositories, fetching the full history first can resolve it without needing to force anything:

git fetch --unshallow

Still Not Working?

If --allow-unrelated-histories results in a huge number of conflicts because both sides have substantial, incompatible content under the same file paths, it may be worth stepping back and considering whether merging is really what you want, versus copying specific files or folders manually from one repository into the other. Forcing a merge between two large, genuinely unrelated codebases often produces a messier result than a deliberate, selective copy of just the files you actually need.

It's also worth checking whether this situation was actually intentional in the first place, since the flag exists specifically as a safety confirmation rather than a routine step. Before running it, take a moment to verify with git log on both sides that you're genuinely looking at two histories meant to become one project, not two histories that happen to share a name coincidentally but represent entirely different codebases. Merging unrelated histories by mistake can leave a repository with a confusing, hard-to-untangle commit graph that's much harder to clean up after the fact than it is to avoid in the first place.

A common real-world version of this scenario: creating a new repository on GitHub with an auto-generated README and license file, then trying to push an existing local project into it. Since the GitHub-created repository already has its own initial commit unrelated to your local history, the two need --allow-unrelated-histories to combine — and in that specific case, allowing it is exactly the right move, since both sides are meant to become the same project going forward.

You might also like