"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
What Is ngrok? Share Your Localhost With the Internet
ngrok gives your local app a public HTTPS URL by tunnelling traffic to your machine. What it's for (webhooks, demos, mobile testing), how to use it, the request inspector, free vs paid limits, security cautions, and alternatives like Cloudflare Tunnel.
What Is curl? A Beginner's Guide With Practical Examples
curl is a command-line tool for making web requests, installed on almost every computer. The commands you'll actually use — GET, POST JSON, headers, authentication, following redirects, downloading files, seeing response headers — and how to read API docs that use it.