Merge conflictsAlways fixable

Fix 'refusing to merge unrelated histories'

Git says refusing to merge unrelated histories — what does that mean?

Short answer

The two branches share no common ancestor, so Git won't guess how to combine them. Adding --allow-unrelated-histories permits the merge — but first check you aren't accidentally merging two genuinely different projects, which is what this guard is protecting you from.

quick fix
git pull origin main --allow-unrelated-histories

Permits a merge between two histories with no shared ancestor

Does this match your situation?

  • 'fatal: refusing to merge unrelated histories'.
  • You created a repo on GitHub with a README, then pushed a local repo you'd already started.
  • You're combining two repositories that were developed separately.
  • You re-initialised a repository with git init and lost the connection to the old history.

Step-by-step fix

  1. Check the two histories really do belong together

    This error is a genuine safety check. Look at both sides before overriding it — merging the wrong repository together is far more annoying to undo than the error is to read.

    step 1
    git log --oneline -5 HEAD
git fetch origin
git log --oneline -5 origin/main

  2. The common case: a README-initialised remote

    GitHub's 'Add a README' option creates an initial commit with no relationship to your local history. Merging with the flag joins them and is completely safe here.

    step 2
    git pull origin main --allow-unrelated-histories
# resolve any conflicts (usually just README.md), then:
git add .
git commit
git push -u origin main

  3. Or discard the remote's starter commit entirely

    If the remote only contains an auto-generated README you don't want, overwrite it. Only do this when you're certain the server has nothing of value.

    step 3
    git push --force-with-lease origin main

    This deletes whatever is on the remote branch. Confirm it holds nothing you need.

  4. Merging two real projects together

    To combine separate repositories properly, bring the other one in as a remote and merge it into a subdirectory so nothing collides at the root.

    step 4
    git remote add other ../other-project
git fetch other
git merge other/main --allow-unrelated-histories
# resolve conflicts, commit

  5. Back out if the merge was a mistake

    Abort while it's in progress, or reset afterwards — the pre-merge position is saved in ORIG_HEAD.

    step 5
    git merge --abort

# already committed the merge?
git reset --hard ORIG_HEAD

Why this works

Git merges by finding the most recent common ancestor of two branches and applying each side's changes relative to it. With no shared ancestor there is no base to diff against, so every file on both sides looks like a brand-new addition and the result is a mess of conflicts. Older Git versions allowed this silently, which mostly served to let people merge the wrong repository by accident; since 2.9 you have to state the intent explicitly. The flag doesn't change the merge algorithm — it just confirms you meant it.

How to stop it happening again

  • Create the repository empty on GitHub (no README, no .gitignore) when you already have local history.
  • Or clone the remote first and add your files into that clone.
  • Avoid re-running git init in a project that already has history - it starts a fresh, unrelated timeline.

Commands used in this guide

git merge

Combine another branch's history into the current one.

git pull

Fetch from the remote and immediately integrate the changes into your branch.

git remote

Manage the named URLs your repository syncs with.

git reset

Move the current branch pointer, optionally rewriting the index and your files.

git log

Browse commit history with as much or as little detail as you want.

Still stuck?

Search the full command reference and every other rescue guide — there are 56 of them, covering everything from detached HEAD to force-push disasters.

Browse all guides →

Frequently asked questions

What does 'refusing to merge unrelated histories' mean?

The two branches have no commit in common, so Git has no base to merge against. It refuses rather than treat every file as newly added, which is almost always the sign of an accidental merge between different projects.

Is --allow-unrelated-histories safe?

Yes, when the histories genuinely belong together - typically your local project and a GitHub repo initialised with a README. It's unsafe only in the sense that it lets you merge two unrelated projects, which is the mistake the guard exists to catch.

How do I avoid this when creating a repository on GitHub?

Create it completely empty - no README, no .gitignore, no licence. Then git remote add origin and push your existing history, and the two never diverge in the first place.

Related rescue guides

Always fixable

How do I combine two separate repos while keeping both histories?

Add the second repository as a remote, fetch it, and merge with --allow-unrelated-histories into a subdirectory. Both sets of commits end up in one repository with their history intact.

Read the fix →Always fixable

Git says I have merge conflicts — how do I fix them?

Git pauses and marks the clashing sections with <<<<<<<, ======= and >>>>>>>. Edit each file to the version you actually want, delete the markers, git add the file, then git merge --continue. If it gets overwhelming, git merge --abort returns you to exactly where you started.

Read the fix →Always fixable

My push was rejected — 'Updates were rejected because the remote contains work that you do not have'. What now?

Someone pushed commits you don't have yet, so your push would erase them. Git is protecting you. Fetch and integrate their work first with git pull --rebase, then push again. Never reach for --force here unless you genuinely intend to delete what's on the server.

Read the fix →Always fixable

How do I undo a Git merge?

If the merge hasn't been pushed, git reset --hard HEAD~1 removes it cleanly. If it has been pushed, use git revert -m 1 <merge-hash> so history stays valid for everyone else. And if you're still in the middle of a conflicted merge, git merge --abort is all you need.

Read the fix →
← All Git Rescue guides