Fix Git 'refusing to merge unrelated histories' error

You tried git pull or git merge and Git bailed because the two branches share no common commit. Here's why it happens and the two ways to fix it — one safe, one that rewrites history.

You're on your local branch, you type git pull origin main, and Git spits back:

fatal: refusing to merge unrelated histories

This usually happens right after you've created a new repository on GitHub, initialized a local repo with git init, added a remote, and then tried to pull the remote's README or .gitignore. You've got two completely separate histories — your local commits and the remote's commits — and Git refuses to merge them because there's no common ancestor commit.

The root cause is simple: Git only merges branches that share a base commit. When you clone a repo, you get that shared base. But when you git init locally and then add a remote that already has commits, your histories are like two strangers at a party — no mutual friends. Git doesn't know which changes to keep, so it taps out.

Why this happens — plain English

Think of each repository as a family tree. Cloning gives you the same ancestors. But if you create a repo from scratch and then connect it to an existing remote, you've got two separate family trees with zero overlap. Git's merge logic relies on finding a common ancestor to figure out what changed. Without one, it can't do the diff properly, so it throws that error.

The most common scenario: You created a local project with git init, made a few commits, then created a blank repo on GitHub (with a README, license, or .gitignore). When you add that as your remote and try git pull origin main, boom — you hit the error.

How to fix it (the safe way first)

You have two options. The first is what I recommend for most people because it doesn't rewrite anyone's history.

Option 1: Use --allow-unrelated-histories

This flag tells Git, "I know these histories are unrelated, merge them anyway." Git will do a three-way merge and create a merge commit. You'll likely get conflicts if both sides have similar files (like a README). That's normal — just resolve them.

Run the pull with the flag:
```
git pull origin main --allow-unrelated-histories
```
After you run this, Git will open your default editor for a merge commit message. Save and close. If there are conflicts, you'll see them in the terminal.
Resolve any conflicts: Open the conflicting files, decide what to keep, and save. For a README, you might keep the remote's version and delete yours, or merge them.
Stage and commit:
```
git add .
git commit -m "Merge remote main into local branch"
```
After this, your local branch now shares the remote's history. Future pulls should work normally.

Option 2: Rebase (only if you want a cleaner history)

If you don't want a merge commit, you can rebase your local commits on top of the remote. This rewrites your commit history — so only do this if you're the only one using your local branch. If you've pushed to a shared remote, skip this.

Fetch the remote first:
```
git fetch origin
```
You'll see the remote branches updated.
Rebase onto the remote branch:
```
git rebase origin/main --allow-unrelated-histories
```
Git will replay your local commits on top of the remote's latest commit. Fix any conflicts that appear, then git add . and git rebase --continue.
Push your rebased branch:
```
git push -f origin main
```
Note the -f — you're force-pushing because you changed history. If you're unsure about force-pushing, don't. Stick with Option 1.

What to check if it still fails

Are you pulling the right branch? Run git branch -a to see all branches. Maybe the remote uses master instead of main. If so, swap it in: git pull origin master --allow-unrelated-histories.
Did you spell the remote correctly? Run git remote -v. If the URL looks wrong, fix it with git remote set-url origin <correct-url>.
Is your local repo actually empty? If you have no commits locally, Git might still complain. You can just do git pull origin main --allow-unrelated-histories — it'll work.
Still seeing the error? Maybe you're not on a branch that tracks the remote. Run git branch --set-upstream-to=origin/main main, then try the pull again.

One last thing: if you're in a hurry and your local commits are junk anyway, you can just delete your local repo and clone fresh. That's the nuclear option, but it's sometimes the quickest.

Remember: --allow-unrelated-histories is a one-time thing. Once you've merged or rebased, your histories are joined, and you won't see this error again — unless you end up with another unrelated remote, but that's a different problem.