Fix Git 'refusing to merge unrelated histories' error

You're stuck on this error and it's annoying. Here's the fix.

The error fatal: refusing to merge unrelated histories shows up when Git can't find a common commit between the two branches you're trying to merge. This usually happens when you've created a new repo locally, added some commits, then tried to pull from or merge with a remote repo that already has its own history. They're two separate lineages.

The one-liner that fixes it 95% of the time

git pull origin main --allow-unrelated-histories

Or if you're merging a branch:

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

The --allow-unrelated-histories flag tells Git: "I know these branches don't share a common ancestor. Merge them anyway." Git will combine everything into a single branch, and you'll likely have to resolve merge conflicts manually. That's expected.

Why does this happen in the first place?

Git track history as a directed acyclic graph of commits. Every commit points back to its parent(s). When two branches have no shared parent commit—like when you git init a local repo and make commits, then add a remote that already has commits—Git sees two orphaned histories. It refuses to merge them by default because it can't reconcile the lineages automatically.

Common scenarios:

• You created a local repo with git init, added files, committed them. Then you added a remote that already had commits (e.g., from a GitHub template).
• You cloned a repo, then deleted the local .git folder and re-ran git init, made commits, and tried to push to the same remote.
• You used git checkout --orphan to create a branch with no history—then tried to merge it back.

When you shouldn't use --allow-unrelated-histories

Don't use this flag just because you don't feel like rebasing or resolving conflicts properly. If the branches actually do share a common ancestor (you can verify with git merge-base branch1 branch2), then the error means something else—like a corrupted repo or a misconfigured remote URL. In that case, check your remotes with git remote -v and make sure you're not pulling from a completely different repo.

Also: if you're working on a team project and someone else's branch throws this error when you try to merge, stop and ask if they rebased or force-pushed. Using --allow-unrelated-histories blindly could duplicate commits and make a mess.

Less common variations you'll run into

1. The error shows up on git push

You'll see it as ! [rejected] main -> main (non-fast-forward) or sometimes just a generic fetch first message. This happens when you've created a local repo and the remote has commits you don't have. The fix is the same: git pull origin main --allow-unrelated-histories, resolve conflicts, then push.

2. The error shows up on git fetch or git rebase

Fetch doesn't merge, so it won't throw this directly. But if you try to rebase a branch with no common ancestor, you'll get the same error. Use git rebase main --allow-unrelated-histories or just merge instead.

3. Working with git submodules

If a submodule's history gets detached or replaced, you might see this when updating. In that case, cd into the submodule directory and run git pull origin main --allow-unrelated-histories there. Then back in the parent repo, git add submodule-path and commit.

How to prevent this from happening again

The easiest fix is to never create a blank local repo when you plan to use an existing remote. Instead:

• Clone first: git clone https://github.com/user/repo.git
• If you already have local files, clone the remote into a separate folder, then copy your files into it and commit.
• If you're starting from scratch with a new local project and a new remote, create the remote first with a README or .gitignore (on GitHub/GitLab), then clone that. Or create the local repo, add a remote, but don't make any local commits before pulling from the remote.

If you absolutely must initialize a local repo and later connect it to a remote that already has history, just remember the flag. Keep it in your back pocket. You'll use it maybe once a year if you're careful.

One last thing: after you merge with --allow-unrelated-histories, you'll end up with a merge commit that has two parent commits—one from each lineage. This is fine, but it means your Git graph will look weird to anyone who clones after you. It's not a big deal, but don't make a habit of it.