How to Fix ‘fatal: refusing to merge unrelated histories’

Quick Answer: The error fatal: refusing to merge unrelated histories occurs when you try to pull or merge two repositories that do not share a common ancestor commit (e.g. initializing a local repo and pulling a GitHub repo created with its own initial README). To fix it, append the flag --allow-unrelated-histories to your pull command: git pull origin main --allow-unrelated-histories.

Why Does This Error Happen?

Git calculates branch relationships by finding a Lowest Common Ancestor (LCA) commit.

If you create a local repository with git init and make local commits, and separately create a GitHub repository initialized with a README.md or .gitignore, both repositories have independent root commits. Because they share no common history, Git’s safety check prevents an accidental merge.

Step-by-Step Fix

Fix 1: Pull with --allow-unrelated-histories (Recommended)

Run git pull with the --allow-unrelated-histories flag:

$ git pull origin main --allow-unrelated-histories

Git will combine the commit graphs of both repositories and open a commit editor to finalize the merge commit. Save and exit to complete.

Fix 2: Rebase with --allow-unrelated-histories

If your project workflow prefers a linear history instead of a merge commit:

$ git pull --rebase origin main --allow-unrelated-histories

What Happens Under the Hood?

When merging, Git inspects commit parent hashes (.git/objects/). If the commit DAG (Directed Acyclic Graph) of branch A and branch B have different root commits with no shared parent ancestor, Git halts the merge step before writing tree objects.

Passing --allow-unrelated-histories explicitly tells Git’s merge engine to synthesize a common root and construct a 3-way merge between the two independent histories. Learn more about tree objects and merge resolution in /git-merge and /git-objects.