Git: fatal: refusing to merge unrelated histories
Two root commits and no merge base. Decide whether to keep both, adopt the remote, or replay your work, then use --allow-unrelated-histories only when the merge is really what you mean.

Introduction & Quick Summary
Symptom. The first pull from a new remote fails, and the merge never starts:
$ git pull origin main
fatal: refusing to merge unrelated historiesCause. The two sides have no common ancestor. Git merges histories by finding a merge base; with two independent root commits there is none, and since Git 2.9 that case is refused instead of producing a merge whose diff contains the entire project twice. It appears in three situations: a local repository created with git init pulling from a remote created with a README, a .git directory copied into a different project, and two repositories that really are separate projects being joined.
Fix. Decide which history you want to keep before adding the flag. git merge --allow-unrelated-histories origin/main keeps both, with add/add conflicts where both sides created the same file. git reset --hard origin/main discards local history and takes the remote. git rebase replays your commits on top of the remote's. Each produces a different repository, and only one of them is what you meant.
Core Mechanics, Signatures & Reproducible Setup
A merge needs a base commit. git merge-base A B prints nothing when histories are unrelated, and git rev-list --max-parents=0 HEAD shows more than one root in the combined history:
git merge-base HEAD origin/main ; echo "exit: $?"
# exit: 1 -> no common ancestor
git rev-list --max-parents=0 HEAD # root(s) of local history
git rev-list --max-parents=0 origin/main # root(s) of the remote
git log --oneline --graph --all --decorate -20A reproduction in two directories:
# local work with its own root
mkdir local && cd local && git init -q
echo "print('app')" > app.py && git add . && git commit -qm "initial app"
# remote with a README commit, created on the hosting service
cd .. && mkdir remote && cd remote && git init -q
echo "# project" > README.md && git add . && git commit -qm "Initial commit"
git branch -m main
# wire them together
cd ../local
git remote add origin ../remote
git fetch -q origin
git merge origin/main
# fatal: refusing to merge unrelated historiesThe same command with the flag, and the conflict it produces:
git merge --allow-unrelated-histories origin/main
# CONFLICT (add/add): Merge conflict in README.md
# Automatic merge failed; fix conflicts and then commit the result.The flag is only about the missing base. Everything after it is an ordinary merge, including conflict resolution and a merge commit with two parents.
Key Comparison Table
What the situation usually is, and what to do:
| Situation | Keep | Command |
|---|---|---|
git init locally, remote has README | Both | git pull --allow-unrelated-histories origin main |
| Local work is the real history, remote is empty scaffolding | Local | git push --force-with-lease origin main |
| Remote is the real history, local was an experiment | Remote | git fetch origin && git reset --hard origin/main |
| Two real projects being joined | Both, as a merge | git merge --allow-unrelated-histories then resolve |
| Importing another repository as a subtree | Both, nested | git subtree add --prefix=vendor/lib <repo> main |
Options and their consequences:
| Option | History shape | Data at risk |
|---|---|---|
--allow-unrelated-histories | One merge commit, two roots | Nothing; conflicts must be resolved |
git reset --hard origin/main | Remote only | All local commits not pushed |
git rebase origin/main | Local commits replayed on remote tip | Conflict resolution, not commits |
git push --force-with-lease | Local only | Every remote commit not fetched |
--squash plus the flag | One commit on top of local root | The remote's history |
Practical Edge Cases, Error Fixes & Deep Dive Code Examples
1. The first-push order
The most common path into this error is a push that was rejected:
git push -u origin main
# ! [rejected] main -> main (fetch first)
git pull
# fatal: refusing to merge unrelated historiespull is fetch plus merge, and the merge is what fails. Two safe endings:
# Keep both, local history on top of the remote's README commit
git pull --allow-unrelated-histories origin main
# resolve README conflict, then
git push -u origin main
# Or adopt the remote and replay your work as one commit
git fetch origin
git reset --soft origin/main # keeps files staged, moves HEAD
git commit -m "Add application"
git push -u origin main--soft is the difference between the second option being useful and being destructive: history is replaced, work is not lost.
2. Resolving the add/add conflicts
Two roots both adding README.md, .gitignore or LICENSE produce add/add conflicts, and Git shows the whole file from each side:
git status --short
# AA README.md
git checkout --ours README.md # keep your version
git checkout --theirs .gitignore # take the remote's
git add README.md .gitignore
git commit # concludes the merge--ours and --theirs refer to the branches of the merge in progress, not to "my code" and "their code" in an abstract sense: during git pull origin main while on main, --ours is your local main and --theirs is origin/main. Merge the content by hand when both versions matter; the merged file is what everyone reads later.
3. Putting your commits on top of the remote
If the remote's root commit is the scaffolding and your local commits are the actual work, a rebase gives a linear history without an extra merge commit:
git fetch origin
git rebase origin/main
# Successfully rebased and updated refs/heads/main.
git push -u origin main # may need --force-with-lease if main already existsRebase rewrites your commits onto the remote root, so the result has one root and a clean sequence. Test it on a copy (git clone . /tmp/check) if the local branch has work you cannot reconstruct; git reflog is the undo, and it is reliable only while the old objects exist.
4. Joining two real projects
When both histories are meaningful, the merge is the right answer and the flag is just permission to make it. Protect the reviewers from a merge commit that touches every file:
git merge --allow-unrelated-histories --no-commit origin/main
git diff --cached --stat | tail -5
git commit -m "Merge legacy importer history"--no-commit lets you inspect the staged result before it becomes a merge commit. If the diff looks like the whole project added twice, the two repositories probably should not be merged — a subtree or a submodule keeps them separate.
5. When the remote content is expendable
A remote created automatically with a README that nobody wants can simply be overwritten. Do it with a lease and a backup branch, not with --force:
git branch backup/remote-main origin/main # keep the old remote state locally
git push --force-with-lease origin main:main--force-with-lease refuses if someone pushed since your last fetch, which is the protection plain --force lacks. The backup branch costs nothing and answers "what was there before" a week later.
6. Avoiding the situation
The error almost always comes from creating a repository in two places at once. The reliable order is:
# either start from the remote
git clone git@github.com:org/repo.git && cd repo
# or create the remote empty: no README, no .gitignore, no license
git init && git add . && git commit -m "initial" && git remote add origin <url>
git push -u origin mainCreating the remote with a README is convenient, but it means every local git init will meet this error on its first pull. If the platform offers "create empty repository", take it.
Common Compilation/Runtime Mistakes & Version Gotchas
git pullwith the flag in the wrong place.git pull --allow-unrelated-histories origin mainworks,git pull origin main --allow-unrelated-historiesalso parses, but a misspelled--allow-unrelated-historyis ignored as an unknown option in some wrapper scripts and the fatal message repeats.git merge --squashwithout the flag. Squash merges still need a base; the refusal appears the same way and the flag applies.- Retrying after
merge --abort. A merge that failed at the base check never started, so--abortreports "no merge to abort"; nothing is broken. git reset --hardto "fix" the pull. It deletes exactly the commits you created locally, with no reflog entry for files never committed.- Copying a
.gitdirectory between projects. It carries the old root and remote config; a freshgit initplusgit addis cleaner and avoids this error entirely. - Assuming a fork shares history. A fork made from an empty template repository, or a repository imported by a platform, can have an unrelated root; check
git merge-basebefore the first merge. - Merge commits in shallow clones.
git clone --depth 1fetches one commit with no ancestors, and a later merge with a deeper branch can report missing history;git fetch --unshallowfirst. - Force-pushing over a teammate.
--force-with-leaseis the safe form, and it still overwrites their work if you fetched after they pushed a branch they had not rebased. Coordinate the branch, not the flag.
Related tools. Put the two versions of a conflicted file side by side in the text diff tool to see which lines each root introduced — add/add conflicts show the whole file as changed, and the useful comparison is often against the previous release rather than against the other branch — and keep the merge commit message factual about what was joined.
Official references
primary documentationThe Git documentation that defines the behaviour this guide explains.
Try matching browser tools
All toolsSmall utilities that fit Git work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Git guides
All Git guidesGit Push Rejected GH001: Large Files and History Rewrite
The 100 MB limit applies to every blob in the pushed history, so deleting the file does not help. Find the object, rewrite with filter-repo, or migrate to LFS.
Git Tags: Lightweight vs Annotated and SemVer Release Tags
An annotated tag stores the tagger, date, and message; describe and --follow-tags only use those. How v:refname sorting and versionsort.suffix fix pre-release order.
git rebase --onto vs cherry-pick: Recovering a Detached HEAD
Commits made on a detached HEAD belong to no branch. Rescue them from the reflog, then transplant them with rebase --onto or copy them with cherry-pick.
Git Detached HEAD and Non-Fast-Forward Push Rejected
A detached HEAD records commits on no branch, and a rejected push protects commits you do not have. Recover with a branch and reflog; integrate before pushing.
More in Git
All Git guidesThe guides filed next to this one in Git, in library order.