Fix Git 'refusing to merge unrelated histories'

Fix Git 'refusing to merge unrelated histories'

fatal: refusing to merge unrelated histories

or via git pull:

fatal: refusing to merge unrelated histories
hint: Use --allow-unrelated-histories to override.

Why This Happens

Git's merge and pull commands require a common ancestor commit. If no common ancestor exists, Git calls these "unrelated histories" and refuses by default.

The most common scenario:

1. You create a new repository on GitHub with "Initialize with README" checked
2. Separately, you git init a local project and make commits
3. You try git pull origin main — and get this error

The GitHub repo and your local repo have completely separate commit graphs. Git won't merge them automatically because it has no way to know which files from each side should take precedence — or if this is even intentional.

Other scenarios where this occurs:

• Combining two previously separate repositories
• Reinitializing a repo and losing the .git directory
• Using git checkout --orphan to create a branch with no history, then trying to merge it into an existing branch

The Fix

Pass --allow-unrelated-histories to explicitly tell Git you intend to join these separate histories:

git pull origin main --allow-unrelated-histories

or if you're using git merge directly:

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

Git will open your editor for a merge commit message (default: "Merge branch 'main' of ..."). Save and close to complete the merge.

If there are conflicting files (e.g., both sides have a README.md), resolve them as you would any merge conflict, then:

git add README.md
git commit

After the Fix

Push the merged history back to the remote:

git push origin main

If the push is rejected because the remote history and your local history diverged, you may need:

git push origin main --force-with-lease

Use --force-with-lease rather than --force — it checks that no one else pushed to the remote since your last fetch before overwriting.

Prevention

The root cause is usually initializing a GitHub repo with content (README, .gitignore, LICENSE) and then also doing git init locally instead of cloning.

Right approach:

1# Option A: Create empty repo on GitHub (no README), then:
2git init
3git add .
4git commit -m "initial commit"
5git remote add origin https://github.com/user/repo.git
6git push -u origin main
7
8# Option B: Initialize README on GitHub, then clone:
9git clone https://github.com/user/repo.git
10cd repo
11# copy your project files in
12git add .
13git commit -m "add project files"
14git push

Both approaches avoid the diverged history problem entirely.

See Also

• Fix: Git Push Rejected (non-fast-forward) — when the remote has commits your local branch doesn't
• Fix: Git Detached HEAD — another confusing Git state with a straightforward fix

Frequently Asked Questions

What causes unrelated histories in the first place?

Two repositories that never shared a commit — typically a local repository initialised independently and then pointed at a remote that was created with its own initial commit, such as an auto-generated README. Git refuses because there is no common ancestor to merge from.

Is --allow-unrelated-histories safe?

It is safe in the sense that nothing is lost, but it produces a merge with two roots and often conflicts in files that exist on both sides. Use it when combining genuinely separate histories you want to keep. If one side is a throwaway initial commit, resetting to the other is cleaner.

How do I avoid it when creating a new repository?

Create the remote empty, with no README, licence or gitignore, then push your local history into it. The generated initial commit is what creates the second root. Alternatively clone the remote first and add your files to that working copy.

What if I just want the remote's history to win?

Fetch, then reset your branch to the remote's, accepting that local commits not on the remote are discarded — confirm that is what you want first. If you need those commits, create a branch from your current HEAD before resetting so nothing is lost.

Official References

• Debug Pods — reading pod status, events and container states
• kubectl reference — command syntax, output formats and selectors