Git's "refusing to merge unrelated histories" error fix

I know this error is infuriating — you just want to pull your code and Git acts like your repo and the remote have never met.

Here's the fix. Run this from your local branch:

git pull origin main --allow-unrelated-histories

Swap main for whatever your remote branch is called (master, develop, whatever). If there's a conflict, Git will pause and let you resolve it — same as any other merge. Once you're done:

git add .
git commit -m "Merge unrelated histories"
git push origin main

That's it. Fifteen seconds of your life, gone forever.

Why Git refused in the first place

Git tracks history as a graph of commits. When you merge two branches, it walks back to find a common ancestor — the point where they diverged. If it can't find one, the merge is technically meaningless. Git defaults to refusing because 9 times out of 10, that scenario means you've accidentally pointed your repo at the wrong remote, and merging would splice in an unrelated project's entire commit tree.

The classic trigger: you did git init locally, made a few commits, then ran git remote add origin <url> and git pull. Meanwhile the remote already had its own history (a README, a license, whatever GitHub created when you made the repo). Two separate root commits. No shared ancestor. Error.

Same thing happens when you clone a repo, delete .git to "start fresh," and re-init. Or when you migrate between providers (Bitbucket → GitHub, say) and re-push a repo that already had commits on the new side.

So the flag tells Git: yes, I know these histories are unrelated, do the merge anyway. It creates a merge commit that ties the two roots together. History looks a bit weird in git log --graph for a while, but it works.

The cleaner alternative when you don't have local changes worth keeping

If your local commits are just a README and an initial commit you don't care about, don't bother with the flag. Just nuke it:

cd ..
rm -rf your-repo
git clone <remote-url>
cd your-repo

Nine times out of ten this is what you actually wanted. The --allow-unrelated-histories merge leaves a permanent artifact in your history that future-you will look at and wonder about.

Variations you'll run into

You're on a different branch name

Git 2.28+ defaults new repos to main, older installs still use master. If you type git pull origin main and get couldn't find remote ref main, check with git ls-remote --heads origin. That lists every branch on the remote with its SHA. No guessing.

You're rebasing instead of merging

Rebase has no equivalent flag — it can't reconcile unrelated roots because there's no base to replay onto. If you've been told "rebasing is cleaner," sure, but not here. Do the merge once with the flag, then rebase normally afterward.

You used git init and there's a nested repo

Sometimes the error shows up because you accidentally git init'd inside an existing repo (a subfolder that already had a .git). Check with ls -la in the directory and its parents. If you find a stray .git, remove it and try again. This one bites people who download a template as a zip — the zip usually includes a .git folder.

Orphan branches and GitHub Pages

The gh-pages branch is often created as an orphan with no common ancestor to main. If you're pushing a Pages deploy and trying to merge back, you'll see this error. That's expected — don't force it. Keep gh-pages separate, or set up a proper GitHub Action to build it.

Corporate mirrors and forks

If your company mirrors an upstream repo into an internal GitLab and you clone both, then try to reconcile — same problem. The mirror has its own initial commit. Use the flag on the internal side only, and never push the merged result back upstream. You'll break their history.

Stopping it from happening again

The rule is simple: pick one source of truth and stick to it.

• If the remote already exists, clone it. Don't git init and then try to attach.
• If you need a blank local repo, create it empty on the remote too — no README, no .gitignore, no license. GitHub gives you that option at repo creation and it's the right call when you're pushing existing work.
• Never delete .git as a troubleshooting step. It's where all your history lives. If something's broken, fix the config, don't nuke the folder.
• When migrating between hosts, use git clone --mirror and git push --mirror. That preserves refs and history exactly. A regular clone-and-push loses branches and can create the exact situation we just fixed.

Run git remote -v before any pull if you're unsure which remote you're pointing at. Takes two seconds and saves the whole mess.