Fixing Git 'refusing to merge unrelated histories'

What the error means

Git shows "fatal: refusing to merge unrelated histories" when two branches have no common ancestor (e.g., a local repo and a remote initialized separately with their own first commits). This is common when:

• You created local commits, then added a remote that already has an initial commit (README, LICENSE).
• You are combining two independent repositories.
• You are merging an orphan branch (created with --orphan) into a normal branch.

Quickstart: most common fix

Scenario: You have a local repo; the remote was initialized with a README on the default branch (often main). You want to pull and integrate both histories.

1. Ensure you are on the correct local branch

git status
# If needed, rename and switch to match remote default
git branch -M main

1. Fetch remote and pull with explicit permission to combine histories

git remote add origin <REMOTE-URL>  # if not set
git fetch origin
git pull origin main --allow-unrelated-histories

1. Resolve any conflicts, then commit

# Edit files to resolve conflicts
git add -A
git commit  # completes the merge

1. Push to the remote

git push -u origin main

This creates a merge commit that ties the two previously unrelated histories together.

Minimal working example (MWE)

Reproduce the error, then fix it.

# Create repo A with its own history
mkdir A && cd A
git init
printf "A\n" > a.txt
git add a.txt && git commit -m "A: initial"
cd ..

# Create repo B with a separate history
mkdir B && cd B
git init
printf "B\n" > b.txt
git add b.txt && git commit -m "B: initial"

# In repo B, add A as a remote and try to merge
git remote add A ../A
git fetch A
# This fails because histories are unrelated
set +e; git merge A/master; set -e
# fatal: refusing to merge unrelated histories

# Fix: allow unrelated histories
git merge A/master --allow-unrelated-histories
# Resolve conflicts if any, then
git add -A && git commit -m "Merge A into B: combine unrelated histories"

When to use which approach

Choose the method that matches your intent.

• Combine both histories (keep everything):
  • Use merge or pull with --allow-unrelated-histories.
• Keep remote, discard local work:
  • Reset to the remote and start fresh.
  • Example:

    git fetch origin
    git reset --hard origin/main
    

• Keep local, overwrite remote:
  • Force push (ensure this is allowed and safe).
  • Example:

    git push --force-with-lease origin main
    

• Import one repo into a subdirectory of another (preserve both histories cleanly):
  • Use git subtree.
  • Example:

    git remote add lib https://example.com/lib.git
    git fetch lib
    git subtree add --prefix=third_party/lib lib main --squash
    

• Advanced: declare a synthetic ancestor to link histories temporarily:
  • Use git replace (expert-only; useful for archival or rewrite flows).
  • Example:

    git replace --graft <commit-in-target> <commit-in-source>
    git merge <source-branch>
    git replace -d <commit-in-target>
    

Step-by-step: resolving a typical local-vs-remote init mismatch

1. Confirm remote and default branch

git remote -v
git ls-remote --symref origin HEAD

1. Align branch names (e.g., master to main)

git branch -M main

1. Pull with explicit permission, resolve, push

git pull origin main --allow-unrelated-histories
# resolve, add, commit
git push -u origin main

Conflict tips

• Prefer one side globally (use with care):
  • Keep current branch’s changes:

    git merge -X ours <other>
    

  • Take incoming changes:

    git merge -X theirs <other>
    

• Typical low-risk conflicts: README.md, LICENSE, .gitignore. Decide the preferred variant and standardize going forward.
• Line endings: set consistent normalization before merging to reduce noise.
  • Example .gitattributes snippet:

    * text=auto eol=lf
    

Pitfalls

• Accidental history union: Merging unrelated histories permanently links them. If that wasn’t intended, revert the merge before pushing:

  git log --oneline --graph
  git revert -m 1 <merge-commit-sha>
  

• Protected branches: Force-push and non-fast-forward merges may be blocked by branch protections. Coordinate changes or use a PR.
• Shallow clones: Pulling with unrelated histories from a shallow clone can fail or miss context. Unshallow first:

  git fetch --unshallow
  

• CI pipelines: Paths may collide (e.g., same filename different content). Update build scripts or restructure directories.

Performance notes

• Large merges can be slow due to rename detection and diffing. If necessary:
  • Temporarily disable rename detection for the merge:

    git -c merge.renames=false merge <other> --allow-unrelated-histories
    

  • Or adjust similarity threshold:

    git merge -X find-renames=95 <other> --allow-unrelated-histories
    

• Reduce working set when integrating large repos:
  • Use sparse-checkout for targeted directories.
  • Fetch shallow history first, then deepen if needed.
• Clean up storage after big merges:

  git gc
  

Frequently asked questions

• Why does this happen?

  • The branches have no common ancestor. Typical with separately initialized repos or orphan branches.

• Is --allow-unrelated-histories safe?

  • Yes, if you truly want both histories combined. It creates a merge commit linking them. If unsure, consider subtree or keeping one side.

• Can I make Git always allow this?

  • You can set a config, but use cautiously:

    git config --global merge.allowUnrelatedHistories true
    

• Will rebase help instead of merge?

  • Generally no. Rebase expects a common base. Use a merge (or subtree) to connect unrelated roots.

• How do I handle master/main mismatches?

  • Rename your local branch to match the remote and then pull with the flag:

    git branch -M main
    git pull origin main --allow-unrelated-histories
    

Summary

Use --allow-unrelated-histories when you intentionally need to combine independent histories. Otherwise, prefer resetting to one side, force-pushing, or using git subtree to keep histories organized. Always resolve conflicts carefully and verify CI after the merge.