Fix: fatal: refusing to merge unrelated histories

The Error

You try to pull, merge, or rebase and Git refuses with:

fatal: refusing to merge unrelated histories

Why This Happens

Every Git repository starts with an initial commit. When you merge two branches, Git looks for their common ancestor commit — the point where they diverged. If two branches have no common ancestor at all, Git considers them “unrelated histories” and refuses to merge them.

This is a safety mechanism. Git is telling you: these two histories have absolutely no shared starting point, so combining them may not be what you intended. Under the hood, Git’s merge algorithms (recursive, ort, octopus) all start by computing a merge base via git merge-base. With no shared commit, there is no base to diff against, so a three-way merge cannot run. Forcing the operation requires an explicit opt-in flag.

The most common scenarios where this occurs:

• You ran git init locally, then tried to pull from a remote that already has commits. Your local repo and the remote repo each have their own unrelated initial commits.
• A GitHub repo was created with a README, license, or .gitignore, and you try to push/pull a local repo into it. GitHub created an initial commit, and your local project has its own separate initial commit.
• You’re trying to combine two completely separate repositories into one.
• A shallow clone (git clone --depth=1) lost its connection to the full history, making Git unable to find the common ancestor.

Git Version History: Why This Error Exists at All

The reason this error trips so many developers is a deliberate behavior flip in Git 2.9 (released June 2016). Before 2.9, git pull would silently merge unrelated histories without warning, which led to disasters where engineers accidentally combined two unrelated projects and ended up with garbled README.md files mixing two codebases. The 2.9 release notes explicitly state that git merge “used to allow merging two branches that have no common base by default” and that this default was reversed to require --allow-unrelated-histories.

If you are working on a machine that still ships Git older than 2.9 — some long-lived CentOS 7 or RHEL 7 boxes are notorious for this — you will never see this error, but you also lose the safety net. Run git --version to check. Anything below 2.9 should be upgraded; anything below 2.20 is missing years of merge engine fixes (the ort merge strategy became the default only in Git 2.34, October 2021, and dramatically improved performance and conflict accuracy compared with the legacy recursive strategy).

Two other version milestones matter here. Git 2.28 (July 2020) added init.defaultBranch, which is why some people see main while others still see master — the branch name mismatch is itself a frequent cause of “unrelated histories” symptoms because users pull the wrong branch. Git 2.33.1 added --allow-unrelated-histories support to git rebase, which earlier versions silently rejected as an unknown option. Knowing your Git version saves you from guessing why a documented flag does not work.

Fix 1: Allow Unrelated Histories on Pull

This is the most common fix. If you created a repo locally and are pulling from a remote for the first time:

git pull origin main --allow-unrelated-histories

Git will merge the two unrelated histories together. You may get merge conflicts (for example, if both sides have a README.md). Resolve them normally, then commit:

git add .
git commit -m "Merge remote history into local repo"

Fix 2: Allow Unrelated Histories on Merge

If you’ve already fetched the remote branch and want to merge it manually:

git fetch origin
git merge origin/main --allow-unrelated-histories

This gives you the same result as Fix 1 but separates the fetch and merge steps, which can be useful if you want to inspect the remote branch first with git log origin/main.

Fix 3: Allow Unrelated Histories on Rebase

If you prefer a linear history instead of a merge commit:

git rebase --allow-unrelated-histories origin/main

Note: The --allow-unrelated-histories flag on git rebase requires Git 2.33.1 or later. If you get an unknown option error, update Git or use Fix 1 or Fix 2 instead.

Be careful: this replays your local commits on top of the remote branch. If there are many conflicting files, a merge (Fix 1 or 2) is usually easier than resolving rebase conflicts one commit at a time.

Fix 4: GitHub Repo Created With README + Local Project

This is the single most common cause. You created a repo on GitHub and checked “Add a README file,” then tried to push an existing local project:

 ! [rejected]        main -> main (fetch first)

So you tried git pull and got fatal: refusing to merge unrelated histories.

The fix:

git pull origin main --allow-unrelated-histories

If you haven’t pushed anything yet and want a cleaner alternative, you can start fresh:

# Remove the local git history
rm -rf .git

# Clone the GitHub repo and copy your files in
git clone https://github.com/your-user/your-repo.git temp
mv temp/.git .
rm -rf temp

# Now add your files
git add .
git commit -m "Add project files"
git push origin main

Fix 5: Shallow Clone Issues

If you cloned with --depth=1 and now can’t merge or pull (this can also happen when your SSH connection drops during a clone — see Fix: SSH connection timed out):

# Fetch the full history
git fetch --unshallow

# Now pull or merge normally
git pull origin main

If --unshallow doesn’t solve it (for example, if the remote has been force-pushed since the shallow clone), use --allow-unrelated-histories as a fallback.

Why this matters: The --allow-unrelated-histories flag exists because merging two completely separate commit trees is almost never accidental. Git blocks it by default to prevent you from accidentally combining a project with an entirely different codebase.

When Is It Safe vs Dangerous?

Safe to use --allow-unrelated-histories:

• You just created a repo on GitHub with a README and you’re connecting a local project to it. This is the textbook use case.
• You’re intentionally combining two repos into one (a monorepo migration, for example).
• A shallow clone caused Git to lose track of the common ancestor.

Be cautious:

• If you don’t recognize the remote branch or aren’t sure why the histories are unrelated. This flag effectively merges two completely separate codebases, which could bring in unexpected files.
• If you’re on a shared branch and other people’s work might be affected.

The flag itself doesn’t skip conflict resolution — you’ll still see and resolve any conflicts. The risk is not data loss, it’s merging in a history you didn’t intend to.

How To Confirm Two Histories Are Truly Unrelated

Before applying the flag blindly, prove the histories are unrelated. Run:

git merge-base origin/main HEAD

If this command prints nothing (or returns a non-zero exit code with the message “fatal: Not a valid commit name”), then the two refs share no common ancestor and --allow-unrelated-histories is the correct tool. If it does print a commit SHA, the real problem is different — usually a force-push that rewrote history, in which case you want a different remediation such as git reset --hard origin/main (after stashing your work) rather than an unrelated-history merge.

A second useful diagnostic:

git log --oneline --all --graph --decorate

This visualises whether the two branches actually meet anywhere. If you see two disconnected graphs, they really are unrelated.

Still Not Working?

If you get merge conflicts after allowing unrelated histories, resolve them like any normal merge conflict:

# See which files conflict
git status

# Edit the conflicting files, then
git add .
git commit

If you get fatal: couldn't find remote ref main, your remote branch might be named master instead:

git pull origin master --allow-unrelated-histories

Check which branches exist on the remote:

git remote show origin

Pro Tip: To avoid this problem entirely on new projects, create the GitHub repo without a README, license, or .gitignore. Push your local project first, then add those files in a subsequent commit.

If you keep hitting this error on every pull, your local branch may not be tracking the remote branch correctly:

git branch --set-upstream-to=origin/main main

If you see the error after a git filter-branch or git filter-repo rewrite, the rewrite changed every commit SHA, so the local branch and the remote no longer share ancestry even though they once did. Treat the remote as the source of truth and re-clone, or push the rewritten history with git push --force-with-lease (after coordinating with collaborators — see Fix: git push rejected — non-fast-forward error for the safer flag variant).

If the error appears in CI but not locally, your CI runner is probably doing a shallow clone. GitHub Actions defaults to fetch-depth: 1 on actions/checkout. Set fetch-depth: 0 to clone the full history so merge bases can be computed.

If a git subtree add is failing with this error, pass --squash explicitly. Subtree merges of unrelated histories are exactly the case the flag is designed for, and git subtree add --prefix=lib/foo https://example.com/foo.git main --squash skips the unrelated-history check by design.

If you are pulling from a private mirror that was re-initialised, the mirror may have been recreated with a fresh initial commit. Treat it as a new remote and either re-clone or use --allow-unrelated-histories on the first pull, then never again.

If you are pulling into a worktree created with git worktree add, the worktree’s HEAD may have been pointed at a branch that no longer shares history with the remote after an upstream rewrite. Inspect with git worktree list. The cleanest fix is to remove the affected worktree (git worktree remove path) and recreate it from the current remote tip.

If you migrated a repository from another SCM — for example, an svn2git or hg-fast-export import — the imported branch carries the import’s synthetic initial commit, which never matches the upstream Git repo’s initial commit. The merge needs --allow-unrelated-histories once, and the safe long-term approach is to keep the imported repo as a separate Git remote that you can fetch independently rather than trying to graft it into the main history. Once the initial merge is done, normal Git workflows resume.

If git pull reports “Need to specify how to reconcile divergent branches” before the unrelated-histories error, you are on Git 2.27 or newer with no pull.rebase or pull.ff configuration. Set the policy explicitly so future pulls do not stop on the same prompt:

git config --global pull.ff only

With pull.ff only, a non-fast-forward git pull fails with a clear message instead of producing a surprising merge commit. You can then deliberately choose between git pull --rebase, git pull --no-ff, or the --allow-unrelated-histories flag depending on the situation.

Related: If your git push is being rejected with a “non-fast-forward” error instead, see Fix: git push rejected – non-fast-forward error. For broader Git authentication failures, see Fix: Permission denied (publickey).