git “fatal: refusing to merge unrelated histories”: what it means and how to fix it safely
Two branches are “unrelated” when they don’t share a single commit: each started from its own first commit. Git won’t merge them by default because that usually means a mistake, such as the wrong remote. Very often it’s harmless: the hosting site made a README commit and you made your own first commit locally.
The classic way to get it
git init && git add . && git commit -m "first commit"
git remote add origin [email protected]:you/app.git # repo created WITH a README
git pull origin main
fatal: refusing to merge unrelated historiesThe website made commit A (README). Your machine made commit B. Neither is an ancestor of the other, so there is no common base for a three-way merge. The same happens after rm -rf .git && git init, when a project is moved between hosts by copying files rather than history, or when two separate repos are combined.
Check you’re pointing at the right repository
git remote -v # is that the URL you expect?
git log --oneline -3 origin/main # what's on the other side?
git log --oneline -3 # and on yoursIf the other side is a completely different project, stop: fix the URL with git remote set-url origin <url> instead of merging.
Fix: allow the merge once
git pull origin main --allow-unrelated-histories
# conflicts? edit the files, then:
git add README.md .gitignore
git commit
git push -u origin mainThe flag works only for that one command; it doesn’t change any setting. Files present on both sides with different content (typically README.md, .gitignore, LICENSE) become ordinary conflicts. See git merge conflict markers for reading them.
Other options
| Situation | Do this |
|---|---|
| New empty-ish remote, only a starter README, nobody else uses it | git push --force-with-lease -u origin main replaces it with your history |
| You want a straight line, not a merge commit | git pull --rebase origin main --allow-unrelated-histories puts your commits on top of theirs |
| Your local repo has hardly anything in it | Clone the remote fresh, copy your files in, commit, push |
| Combining two real projects into one | Merge the other into a subfolder: move its files into old-app/ in a commit first, then merge with the flag |
Use --force only on a repository that is yours alone; on a shared one it deletes other people’s commits. git push rejected (non-fast-forward) explains the difference between --force and --force-with-lease.
Avoid it next time
- When creating a repo on the website for code you already have, leave “Add a README”, .gitignore and licence unticked, then push.
- Or create the remote with a README first and
git cloneit, then add your code. - Move projects with
git push --mirroror by changing the remote URL, never by copying files into a newgit init.
Two histories that look the same but won’t merge? Their commit IDs are hashes of content plus parents, so identical files with different parents still get different IDs. The hash generator shows how a one-character change produces a completely different hash.
Git says not a git repository instead? See fatal: not a git repository.
Questions
What does fatal: refusing to merge unrelated histories mean?
The two branches have no commit in common; each began with its own first commit. Git refuses by default because that is often a mistake, such as pulling from the wrong repository.
How do I fix refusing to merge unrelated histories?
If both are the same project, run git pull origin main --allow-unrelated-histories, resolve any conflicts, commit and push.
Is --allow-unrelated-histories safe?
Yes, it only permits that one merge and changes no settings. Check git remote -v first so you are not merging an unrelated project by mistake.
Why did this happen with a new GitHub repository?
The repository was created with a README, .gitignore or licence, which made a first commit on GitHub, while your local repository made its own first commit. Neither descends from the other.
Published .