How to Fix “fatal: refusing to merge unrelated histories” in Git

The Quick 10-Second Fix

To fix the fatal: refusing to merge unrelated histories error in Git, pass the --allow-unrelated-histories flag during your pull command:

git pull origin main --allow-unrelated-histories

(Replace main with master if your primary branch uses the legacy naming convention.)

Why Does This Error Happen?

Since Git version 2.9 (released in 2016), Git introduced a security safeguard. By default, Git refuses to merge two branches that do not share a common ancestor commit.

This almost always happens to beginners in one specific scenario:

1. You initialize a brand-new project locally on your machine using git init and commit your local code.
2. You create a repository on GitHub (or GitLab/Bitbucket) and check the box that says “Add a README file” or “Add .gitignore”.
3. GitHub creates an initial commit on the remote repository containing the README.
4. Your local repository also has an initial commit containing your project code.
5. When you run git pull origin main to synchronize the two, Git looks at both histories, realizes they have two completely separate commit trees with zero shared ancestry, and aborts with:
   
   fatal: refusing to merge unrelated histories.

Step-by-Step Resolution Walkthrough

Step 1: Pull with the Unrelated Histories Flag

Run the pull command while explicitly telling Git that you understand both branches started independently and you want to merge them into a single timeline:

git pull origin main --allow-unrelated-histories

Step 2: Resolve Any Merge Conflicts (If Prompted)

If your local project and the remote repository have files with the exact same name (for example, if both contain a README.md or a .gitignore), Git will pause and ask you to resolve the conflict.

Open the conflicting file in VS Code. You will see Git’s conflict markers:

<<<<<<< HEAD (Current Change: Your Local Code)
# My Local Project Title
=======
# Remote Title from GitHub
>>>>>>> origin/main (Incoming Change)

Choose which version to keep (or click “Accept Both Changes” in VS Code), delete the conflict markers, and save the file.

Step 3: Commit the Merge

Once any conflicts are resolved, stage the resolved files and complete the merge commit:

git add .
git commit -m "chore: merge remote repository with local files"

Step 4: Push to GitHub

Now that the histories are joined, push your local commits to your remote repository:

git push -u origin main

Your repository on GitHub will now reflect your local project files alongside the remote README without any errors.

How to Prevent This in Future Projects

To avoid this error on future repositories, choose one of these two golden rules:

• Option A: When creating a new repository on GitHub, leave all options unchecked (do not add a README, license, or .gitignore). GitHub will show you the exact copy-paste commands to push an existing repository.
• Option B: If you create a repository with a README on GitHub first, clone it to your computer using git clone <repo-url>, and then add your code into the cloned folder.

Frequently Asked Questions

Is using --allow-unrelated-histories safe?

Yes, as long as you intend to merge the two projects. It simply tells Git to combine two trees that started from different root commits. It does not delete or overwrite code automatically.

What if I just want to overwrite the remote repository with my local code?

If the remote repository only has an unwanted placeholder README that you want to completely erase, you can force-push your local branch:

git push -u origin main --force

⚠️ Warning: Only use --force on personal repositories where you are the sole contributor, as it permanently overwrites the remote history.