Fix: fatal: refusing to merge unrelated histories

Updated 2026-03-06

TL;DR: start with the first fix section and run the verification command before changing anything else.

The Error

fatal: refusing to merge unrelated histories

You’ll typically see this when running:

git pull origin main
# or
git merge main
# or
git pull origin main --rebase

The full output looks like:

$ git pull origin main
From github.com:user/my-project
 * branch            main       -> FETCH_ONLY
fatal: refusing to merge unrelated histories

The Fix

  1. Allow the merge explicitly with the --allow-unrelated-histories flag:
git pull origin main --allow-unrelated-histories

Git will merge the two histories together. If there are file conflicts, resolve them:

# Check which files conflict
git status

# Open conflicted files, resolve the markers (<<<<<<<, =======, >>>>>>>)
# Then stage and commit
git add .
git commit -m "Merge remote main into local repo"
  1. If you’re connecting a local project to a new GitHub repo (the most common scenario), here’s the complete workflow:
# You initialized locally
git init
git add .
git commit -m "Initial commit"

# You created a repo on GitHub with a README or LICENSE
git remote add origin git@github.com:user/my-project.git

# This fails:
git pull origin main
# fatal: refusing to merge unrelated histories

# This works:
git pull origin main --allow-unrelated-histories

# Resolve any conflicts, then push
git push -u origin main
  1. If you’d rather rebase instead of merge (cleaner linear history):
git pull origin main --rebase --allow-unrelated-histories

This replays your local commits on top of the remote history. No merge commit. The result is a clean linear timeline. If conflicts arise during rebase, resolve each one:

# Fix the conflicted file, then
git add <file>
git rebase --continue
  1. If you want to start over and keep only the remote version:
# Back up your local work
cp -r . ../my-project-backup

# Clone the remote repo fresh
cd ..
git clone git@github.com:user/my-project.git my-project-clean

# Copy your files into the cloned repo
cp -r my-project-backup/src my-project-clean/src
# ... copy other files you need

cd my-project-clean
git add .
git commit -m "Add local project files"
git push

This avoids the unrelated histories problem entirely by starting from the remote’s history.

Why This Happens

Git tracks history as a directed acyclic graph (DAG). Every commit points to its parent commit, forming a chain back to the initial root commit. When two repositories have completely separate root commits — no shared ancestor anywhere in their history — Git considers them “unrelated.”

The most common trigger: you create a repository on GitHub with a README, LICENSE, or .gitignore (GitHub’s “Initialize this repository” checkbox). That creates a root commit on GitHub. Meanwhile, you run git init locally and make your own root commit. These two root commits have no relationship. When you try to git pull, Git sees two independent histories and refuses to merge them by default.

This safety check was introduced in Git 2.9 (2016). Before that, Git would silently merge unrelated histories, which caused nasty surprises when people accidentally merged completely unrelated projects into each other. Imagine pulling from the wrong remote and having a stranger’s codebase merged into yours. The flag makes this an explicit choice.

It also shows up when you change a remote URL to point at a different repository, or when you git init a folder that already had a .git directory from a different project. Less commonly, corporate monorepo migrations trigger it when stitching multiple repositories into one.

Edge Cases

Submodule merge conflicts. If either history contains submodules, the merge gets complicated. Git can’t auto-merge .gitmodules files well. You’ll need to resolve the submodule references manually:

git pull origin main --allow-unrelated-histories
# Conflict in .gitmodules

# Edit .gitmodules to keep the correct submodule entries
git add .gitmodules
git commit -m "Merge histories and resolve submodule conflicts"

Large file conflicts with Git LFS. If the remote uses Git LFS and your local repo doesn’t (or vice versa), merging unrelated histories can produce pointer files where you expected actual content. Install and configure LFS before merging:

git lfs install
git pull origin main --allow-unrelated-histories
git lfs pull

Shallow clones. If you cloned with --depth 1 (shallow clone), Git doesn’t have full history. This can sometimes trigger the unrelated histories error even when the repos are related, because the shallow clone doesn’t include the common ancestor:

# Unshallow first
git fetch --unshallow origin
git pull origin main

Repeated merges. You only need --allow-unrelated-histories once. After the initial merge connects the two histories, subsequent pulls and merges work normally because Git now has a shared ancestor (the merge commit itself).

Accidentally merging the wrong repo. Before running --allow-unrelated-histories, double-check your remote URL:

git remote -v

If the URL points to the wrong repository, fix it:

git remote set-url origin git@github.com:user/correct-repo.git

Merging an unrelated repo’s history into yours is reversible but messy. Verify the remote first.

Monorepo migrations. When consolidating multiple repos into one, you’ll use --allow-unrelated-histories intentionally. A cleaner approach is to use git subtree:

# Add repo-b's history under a subdirectory
git subtree add --prefix=packages/repo-b git@github.com:user/repo-b.git main

This preserves repo-b’s full commit history nested under packages/repo-b/ without the awkward merge-unrelated-histories commit.

GitHub’s “create with README” trap. The easiest prevention: when creating a new GitHub repo for an existing local project, don’t initialize it with any files. Leave the README, LICENSE, and .gitignore checkboxes unchecked. GitHub will show you the exact commands to push your local repo. No unrelated histories, no conflicts.

# GitHub shows this for empty repos:
git remote add origin git@github.com:user/my-project.git
git branch -M main
git push -u origin main

See Also