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-historiesOr if you're merging a branch:
git merge other-branch --allow-unrelated-historiesThe --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
.gitfolder and re-rangit init, made commits, and tried to push to the same remote. - You used
git checkout --orphanto 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.