"fatal: refusing to merge unrelated histories": How to Fix It
Git refuses to merge two branches that share no common commit — usually because you created a repo locally and another on GitHub with a README. Why it happens, the --allow-unrelated-histories fix, resolving the resulting conflicts, and how to avoid it.
fatal: refusing to merge unrelated histories
You'll usually see this when running git pull right after connecting a local project to a new GitHub repository.
What it means
Every Git repository is a chain of commits going back to a first commit. Normally, two branches you merge share some commit in their past — that's how Git works out what changed.
"Unrelated histories" means the two branches have no commit in common. They started separately. Git refuses to merge them by default, because that's usually a mistake.
The usual cause
- You created a project on your computer and committed to it.
- You created a repository on GitHub and ticked "Add a README" (or a licence, or
.gitignore). That made a first commit on GitHub. - You connected them with
git remote add originand rangit pull.
Now there are two separate histories: yours and GitHub's one-commit history. (git remote add origin)
Other causes: re-running git init in a folder that was already a repo, or pointing a remote at the wrong repository.
The fix
If you're sure both sides belong together, tell Git it's OK:
git pull origin main --allow-unrelated-histories
Git merges the two histories. If both sides have a file with the same name — very often README.md or .gitignore — you'll get a conflict to resolve:
git status # see conflicting files
# edit the files, keeping what you want
git add README.md
git commit
git push -u origin main
The alternative: overwrite GitHub's version
If the GitHub repo only contains an auto-generated README and you don't care about it, you can replace it with your local history:
git push -u origin main --force
This deletes whatever was on GitHub's main. Only do this on a brand-new repository with nothing you need. (Git push rejected)
Check it's really the right repo
Before forcing two histories together, make sure the remote is the repository you think it is:
git remote -v
git log --oneline origin/main
If the remote has unexpected history, you may have the wrong URL — and merging two genuinely different projects makes a mess.
How to avoid it next time
When creating a repository on GitHub for a project that already exists on your computer, leave it completely empty: no README, no licence, no .gitignore. Then:
git remote add origin git@github.com:you/my-app.git
git push -u origin main
No pull needed, no unrelated histories.
EasySpawn connects your server to your repository once and keeps it that way — Claude Code can untangle Git errors like this one for you when they do happen. See how it works or join the waitlist.
Related: git remote add origin · Git Push Rejected · Merge Conflicts Explained · Git and GitHub for Beginners
Keep reading
"Python Is Not Recognized as an Internal or External Command": How to Fix It
On Windows, "'python' is not recognized as an internal or external command, operable program or batch file" (or "pip is not recognized") means Windows can't find Python on your PATH. How to check whether Python is installed, use the py launcher, add Python to PATH, turn off the Microsoft Store alias, and fix pip.
The grep Command: Search Files and Logs Like a Pro
grep searches text for lines that match a pattern — in files, whole folders, or the output of another command. The examples you'll actually use: case-insensitive search, recursive search, line numbers, context around matches, counting, excluding folders, regex, and grepping logs, plus ripgrep.