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.

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.

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.

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

Related: If your git push is being rejected with a “non-fast-forward” error instead, see Fix: git push rejected – non-fast-forward error.