Git fatal: refusing to merge unrelated histories

1. About the error
2. Why do I see this error
3. Solution
4. Before you use the flag

#About the error

fatal: refusing to merge unrelated histories

Introduced in Git 2.9, this is a guard rail. When you merge or pull, Git looks for a shared commit the two histories descend from. If there isn't one, it refuses rather than stitch together two genuinely separate project histories by accident.

#Why do I see this error

• You created a repository locally (with its own commits) and then tried to pull from a remote that was also initialised separately, two roots, no shared ancestor.
• You're merging a branch that was started from scratch rather than branched off the others.
• The .git directory was deleted and recreated, so Git lost the shared history it used to know about.

#Solution

If you've confirmed the merge really is intended (you genuinely want to combine these two histories), pass the override flag:

git pull origin main --allow-unrelated-histories

Or, if you're merging a local branch:

git merge other-branch --allow-unrelated-histories

Git will create a merge commit joining the two roots, and from then on they share history, so you only need the flag once.

#Before you use the flag

The error is often a sign something is off, so it's worth a sanity check first:

• Are you pushing to the right remote? A typo'd remote URL pointing at an unrelated repo triggers this.
• Did you mean to clone instead of init + pull? If the remote already has the project, cloning it fresh avoids the whole situation.

git remote -v   # confirm the remote points where you expect

If the remote is wrong, fix it rather than forcing the merge:

git remote set-url origin git@github.com:you/correct-repo.git

For the related "your push was rejected" situation, see Git updates were rejected (non-fast-forward).