Git: fatal: refusing to merge unrelated histories — Fix It Fast

You run git pull origin main and Git spits back: fatal: refusing to merge unrelated histories. Annoying, but not mysterious. Git is telling you the two branches have no common ancestor commit. It can't figure out how to merge them, so it refuses instead of creating a mess.

This happens most often when you have a local repo with its own commits (maybe you ran git init and started coding) and you're trying to pull from a remote repo that was created separately — like a GitHub repo initialized with a README. No shared history, no merge.

Here's the troubleshooting flow. Start at step 1. Stop when it works.

Step 1: The 30-second fix — allow unrelated histories

If you just want to pull the remote branch and you're okay merging two separate histories, run this:

git pull origin main --allow-unrelated-histories

Replace main with your branch name if it's different (e.g., master, dev). Git will merge the two histories. You'll likely hit merge conflicts, especially if both sides have files with the same names. Resolve them, commit, and you're done.

This is the fix 90% of people need. It's blunt but effective. If you don't care about preserving a clean history and just want the code merged, this is your answer.

Heads up: --allow-unrelated-histories was added in Git 2.9. If you're on an older version, upgrade first. Seriously, no reason to run Git 2.7 in 2026.

Step 2: The 5-minute fix — rebase onto the remote branch

If you want a cleaner history — no weird merge commit tying two unrelated histories together — rebase your local commits on top of the remote branch instead.

First, fetch the remote without merging:

git fetch origin

Then rebase your current branch onto the remote:

git rebase origin/main

Git will replay your local commits on top of the remote's history. You'll still get conflicts if the same files were touched, but the end result is a linear history instead of a merge commit that says "these two repos had nothing to do with each other."

Why this matters: that merge commit from step 1 is ugly. It permanently records that you merged two unrelated histories. Reviewers will ask about it. A rebase avoids that entirely.

If you're on a feature branch and you just want your work on top of the remote's main, this is the right move.

Step 3: The 15-minute fix — cherry-pick or start clean

Sometimes you don't want to merge at all. Maybe your local repo was a mistake — you initialized in the wrong folder, or you have two projects that shouldn't be combined. In that case, forcing a merge is the wrong answer.

Option A: Cherry-pick your commits

Delete your local branch, clone the remote fresh, and cherry-pick the commits you actually want:

git clone https://github.com/user/repo.git
cd repo
git checkout -b my-feature
git cherry-pick <commit-hash-1> <commit-hash-2> ...

You get a clean history, and only the work you care about makes it in. Tedious if you have 50 commits, but for a handful it's the cleanest path.

Option B: Reinitialize and force-push (use with caution)

If the local repo is your source of truth and the remote was just created wrong (empty README, wrong template), you can overwrite the remote:

git remote add origin https://github.com/user/repo.git
git push -u origin main --force

This nukes the remote's history and replaces it with yours. Only do this if you're sure nobody else is using the remote. If a teammate already pulled it, you've just broken their repo.

Don't force-push to a shared branch. I've watched people do this. It never ends well.

Why this error actually happens

Git tracks history as a chain of commits, each pointing to a parent. Two branches can merge only if they share at least one commit in common — a common ancestor. When you create a repo locally with git init and then add a remote that was initialized separately (GitHub's "Initialize this repository with a README" checkbox is the usual culprit), there's no shared commit. Git sees two disconnected trees and refuses to guess how to combine them.

Older Git versions used to merge these silently. Git 2.9 changed the default to refuse, because silent merges of unrelated histories caused confusing results — duplicate files, weird diffs, and "why does my log show two root commits?" questions.

How to avoid this next time

• When starting a new project, either create the repo on GitHub first and git clone it, or create it locally and push with git push -u origin main before adding a README on the remote.
• Don't run git init in a folder you're about to pull into. Clone instead.
• If you must init locally, add the remote and push immediately — before the remote has any commits of its own.
• Check git log --oneline on both sides if you're unsure whether histories are related. No common commit = unrelated.

Quick decision tree

Most people reading this need step 1. Run the command, resolve the conflicts, move on. The other options exist because sometimes you care about history and sometimes you don't. Know which case you're in before you type anything.