You created a repo on GitHub, ticked the box for a README, then tried to push your existing local project into it. Or you pulled from a remote you'd never connected to before. Either way, Git stopped you cold with this:
fatal: refusing to merge unrelated historiesNothing is broken. Git isn't being difficult for no reason here, it's actually doing exactly what it was designed to do. Once you understand why this message exists, the fix takes one line and you'll never be confused by it again.
Why this error exists in the first place
Every commit in Git carries a reference to its parent commit, and that chain going all the way back is what Git calls a project's "history." Two repositories share a history only if one was actually created from the other, through a clone, a fork, or a shared starting commit.
When you create a brand new local repo with git init and separately create a new repo on GitHub with a README, you've made two completely independent histories. They have no common ancestor commit. As far as Git is concerned, these aren't two branches of the same project that drifted apart, they're two unrelated projects that happen to share a folder name.
Merging is built around finding a common ancestor and combining the changes since that point. With no common ancestor at all, Git has no idea how to perform that comparison safely, so since Git 2.9, it refuses by default rather than guessing and possibly producing a nonsense merge.
This is a safety feature, not a bug. It exists specifically to stop you from accidentally smashing two unrelated codebases together without realizing it.
The most common way people hit this
By far the most frequent trigger is the GitHub "Initialize this repository with a README" checkbox. Here's the exact sequence that causes it:
- You build a project locally and run
git init, then make a few commits. - You create a new repository on GitHub and check the box to add a README, a .gitignore, or a license.
- You add that GitHub repo as your remote and try to push or pull.
That checkbox is the problem. It makes GitHub create an initial commit on its end, completely separate from anything in your local repo. Now both sides have commits, but neither history knows the other exists. Git sees two trees with no shared root and stops you right there.
The other common case is pulling from a remote for the first time on a freshly initialized local repo, or merging two genuinely separate projects on purpose, like combining two small repos into one monorepo.
The fix
The flag you need is --allow-unrelated-histories. It tells Git you're aware these two histories don't share a root, and you want it to merge them anyway.
If you're merging directly:
git merge other-branch --allow-unrelated-historiesIf the error showed up during a pull, which is the more common case:
git pull origin main --allow-unrelated-historiesSwap main for whatever branch name your remote actually uses, GitHub defaults to main now but plenty of older repos and other Git hosts still use master.
Run that, and Git performs the merge exactly the way it normally would, just without the ancestor check getting in the way. You'll usually get a normal merge commit, and if both sides touched the same file, you might get a standard merge conflict to resolve, the same as any other merge. Nothing about this flag makes conflict resolution different, it only removes the one specific block on unrelated histories.
If you're on an older Git version
You might come across guides mentioning that older Git versions, before 2.9, didn't have this restriction at all and merged unrelated histories silently. If you're running something genuinely ancient, the flag itself may not even exist or be necessary. Check your version with git --version, though realistically almost everyone today is on a version where the flag is required.
What you'll see when it works
After running the command, you'll get a normal merge confirmation, and if it's a clean merge with no overlapping files, Git opens a commit message editor for the merge commit. Just save and close it, or pass a message inline:
git pull origin main --allow-unrelated-histories -m "Merge initial GitHub commit"Once it's done, your local files and the remote files, like that README GitHub generated, will sit side by side in your working directory. Nothing gets deleted or overwritten unless the exact same file existed on both sides with different content, in which case you'll see normal conflict markers to resolve by hand, just like any other merge conflict.
How to avoid running into this at all
The cleanest fix is preventing the unrelated histories in the first place. When you create a new repository on GitHub specifically to push up an existing local project, leave every initialization option unchecked. No README, no .gitignore, no license. An empty remote repository has no commits at all, so there's no conflicting history to merge against. Your first push just becomes the entire history, clean and simple.
git remote add origin https://github.com/you/your-repo.git
git push -u origin mainIf GitHub already generated files on the remote and you want to add a README or license afterward, just create them locally after your first push and commit them as part of your normal workflow instead of letting GitHub generate a separate starting commit.
When you should think twice before using the flag
The flag is the correct fix for the README scenario almost every time. But pause if you're merging two repositories that were genuinely developed independently for a long time, with lots of commits and possibly overlapping file names or folder structures. In that case, the merge can pull in a large unrelated commit history into your project permanently, bloating your repo size and cluttering your log forever. For that kind of merge, it's worth deciding deliberately, maybe by reviewing what files would actually collide first with a quick diff, rather than just running the command and hoping for the best.
For the everyday case, a fresh local project meeting a freshly initialized GitHub remote, there's no real risk. You're just stitching together two starting points that should have been one from the beginning.
Quick reference
| Situation | Command |
|---|---|
| Merge conflicting histories directly | git merge branch-name --allow-unrelated-histories |
| Pull triggers the error | git pull origin main --allow-unrelated-histories |
| Avoid it entirely on a new GitHub repo | Create the remote repo with no README, .gitignore, or license |
| Check your Git version | git --version |
This error looks alarming the first time you see it, mostly because the word "fatal" makes it sound like something went badly wrong. In reality it's Git asking you to confirm something it can't verify on its own: that these two separate histories are actually meant to become one project. Add the flag, confirm that's what you want, and you're through it in seconds.
