Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

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.

~5 min readGit
#Git#Merge#History#Version Control
3D diagram of two separate commit cube chains joined by an amber bridge being lowered, headline UNRELATED HISTORY

Introduction & Quick Summary

Symptom. The first pull from a new remote fails, and the merge never starts:

code
$ git pull origin main fatal: refusing to merge unrelated histories

Cause. 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:

bash
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 -20

A reproduction in two directories:

bash
# 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 histories

The same command with the flag, and the conflict it produces:

bash
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:

SituationKeepCommand
git init locally, remote has READMEBothgit pull --allow-unrelated-histories origin main
Local work is the real history, remote is empty scaffoldingLocalgit push --force-with-lease origin main
Remote is the real history, local was an experimentRemotegit fetch origin && git reset --hard origin/main
Two real projects being joinedBoth, as a mergegit merge --allow-unrelated-histories then resolve
Importing another repository as a subtreeBoth, nestedgit subtree add --prefix=vendor/lib <repo> main

Options and their consequences:

OptionHistory shapeData at risk
--allow-unrelated-historiesOne merge commit, two rootsNothing; conflicts must be resolved
git reset --hard origin/mainRemote onlyAll local commits not pushed
git rebase origin/mainLocal commits replayed on remote tipConflict resolution, not commits
git push --force-with-leaseLocal onlyEvery remote commit not fetched
--squash plus the flagOne commit on top of local rootThe 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:

bash
git push -u origin main # ! [rejected] main -> main (fetch first) git pull # fatal: refusing to merge unrelated histories

pull is fetch plus merge, and the merge is what fails. Two safe endings:

bash
# 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:

bash
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:

bash
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 exists

Rebase 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:

bash
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:

bash
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:

bash
# 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 main

Creating 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 pull with the flag in the wrong place. git pull --allow-unrelated-histories origin main works, git pull origin main --allow-unrelated-histories also parses, but a misspelled --allow-unrelated-history is ignored as an unknown option in some wrapper scripts and the fatal message repeats.
  • git merge --squash without 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 --abort reports "no merge to abort"; nothing is broken.
  • git reset --hard to "fix" the pull. It deletes exactly the commits you created locally, with no reflog entry for files never committed.
  • Copying a .git directory between projects. It carries the old root and remote config; a fresh git init plus git add is 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-base before the first merge.
  • Merge commits in shallow clones. git clone --depth 1 fetches one commit with no ancestors, and a later merge with a deeper branch can report missing history; git fetch --unshallow first.
  • Force-pushing over a teammate. --force-with-lease is 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 documentation

The Git documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit Git work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Git guides

More in Git

All Git guides

The guides filed next to this one in Git, in library order.