You’ve got two repositories with completely separate histories, and you need to bring them together. Maybe it’s an old project you’re absorbing into a new one, or a submodule that started life as its own thing. You try a standard git merge and Git immediately shuts you down:
fatal: refusing to merge unrelated histories
This isn’t a bug – it’s Git being cautious. When two branches share no common ancestor, Git assumes you’ve made a mistake and refuses to play along. But sometimes you genuinely want this merge, and there’s a flag for that.
The Fix
Git provides --allow-unrelated-histories to override this protection. It tells Git: yes, I know these have nothing in common, merge them anyway.
git merge other_repo/other_branch --allow-unrelated-histories
That’s the core of it. Everything else is just setup and cleanup.
Step by Step
Add the other repository as a remote:
git remote add other_repo https://github.com/someone/other-project.git
git fetch other_repo
Switch to the branch you want to merge into:
git checkout main
Run the merge with the flag:
git merge other_repo/other_branch --allow-unrelated-histories
Sort out any conflicts. Git will flag files where both sides made changes. Edit them, stage the resolved files, and carry on.
Commit and push:
git commit -m "Merged unrelated histories"
git push origin main
A Word of Caution
This flag exists because merging unrelated histories is unusual, and usually a sign that something needs thinking about. Before you use it, ask yourself whether a merge is really the right move, or whether you’d be better off keeping the repositories separate and referencing one from the other.
Once you’ve merged unrelated histories, that history is baked in. You can’t un-merge it cleanly. So take a moment to make sure you’re happy with what you’re doing before you press go.