Executing a standard version control command such as git pull origin main or git merge branch-name on Linux, macOS, or Windows only to be stopped by the error: “fatal: refusing to merge unrelated histories” blocks code integration. The merge aborts immediately, leaving the working directory unchanged and preventing local commits from pushing to GitHub, GitLab, or Bitbucket. This error is an intentional safety guard introduced in Git version 2.9.0. It triggers when two branches being merged do not share a common ancestor commit in their commit tree—typically occurring when initializing a local repository independently while simultaneously creating a remote repository pre-populated with a README.md or .gitignore file. This guide explains how to safely reconcile unrelated commit histories and merge branches without data loss.
Why Does Git Refuse to Merge Unrelated Histories?
Prior to Git 2.9.0, merging two repositories that started independently was permitted by default. However, this frequently caused catastrophic accidental merges when developers mistakenly pulled from completely different projects into their working trees. Git now requires explicit operator confirmation:
- Independent Initial Commits: Running
git initlocally creates an initial root commit (e.g., Commit A). Meanwhile, creating a repository on GitHub with an initialized README generates a separate root commit (Commit B). Because Commit A and Commit B share no common ancestor, Git rejects the merge. - Re-initialized Repositories: Accidentally deleting the local
.gitdirectory and runninggit initafresh wipes historical commit trees, severing the link to upstream remotes. - Combining Two Distinct Projects: Intentionally merging two independent codebases (such as merging a frontend repository and backend repository into a monorepo).
Method 1: Use the –allow-unrelated-histories Flag with git pull
The standard, verified resolution when pulling from a newly created remote repository that contains a default README or license is passing the --allow-unrelated-histories override flag.
- Open your Linux terminal and navigate to your local Git repository:
cd ~/projects/my-repo - Execute
git pullwith the unrelated histories flag explicitly specified:git pull origin main --allow-unrelated-histories - Note: Replace
mainwithmasterif your upstream branch uses legacy branch naming. - Git will fetch the remote tree and automatically create a merge commit combining both root histories.
- If your default text editor (such as Nano or Vim) opens displaying a merge commit message (e.g., “Merge branch ‘main’ of https://github.com/…”), save and close the editor (Ctrl + O and Ctrl + X in Nano, or
:wqin Vim). - Push your combined commits back to the remote repository:
git push origin main
Method 2: Resolve File Conflicts During the Merge
If both the local and remote repositories contain identically named files (such as README.md or package.json) with different contents, Git will pause with merge conflicts.
- After running
git pull origin main --allow-unrelated-histories, Git will report:CONFLICT (add/add): Merge conflict in README.md Automatic merge failed; fix conflicts and then commit the result. - Check which files are conflicted:
git status - Open the conflicted files in your editor (e.g., VS Code or Nano). Locate the standard Git conflict markers:
<<<<<<< HEAD Your local content ======= Remote repository content >>>>>>> [commit-hash] - Edit the file to retain the desired content and delete the conflict markers.
- Stage the resolved files:
git add README.md - Complete the merge commit:
git commit -m "Merge remote and local unrelated histories and resolve conflicts" - Push the resolved branch to the upstream remote:
git push origin main
Method 3: Merge Two Local Branches with Unrelated Histories
If you are creating a monorepo or merging two distinct branches that originated from different roots on your local machine, pass the flag to git merge.
- Ensure you are on the target branch:
git checkout main - Execute the merge command with the override parameter:
git merge feature-branch --allow-unrelated-histories -m "Merge feature-branch into main" - Verify the integrated commit graph:
git log --oneline --graph --decorate - The output will display two distinct root origins converging into your latest merge commit.
Method 4: Rebase Local Commits onto the Remote Branch (Alternative)
If you prefer a clean, linear commit history without an explicit merge commit, rebase your local commits on top of the remote branch.
- Fetch the latest remote tracking branches without merging:
git fetch origin - Rebase your current branch onto the remote branch:
git rebase origin/main - If Git reports conflicts, resolve them, run
git add <file>, and proceed with:git rebase --continue - Once rebased, push your linear history upstream:
git push origin main
Troubleshooting Summary for Git Unrelated Histories Error
| Git Operation | Command Syntax | Resulting History Structure |
|---|---|---|
| Remote Pull | git pull origin main --allow-unrelated-histories |
Creates a 2-parent merge commit combining remote and local roots |
| Local Branch Merge | git merge <branch> --allow-unrelated-histories |
Joins two distinct local repository branches into a single tree |
| Conflict Resolution | Edit conflict markers > git add > git commit |
Reconciles conflicting duplicate files (such as README or .gitignore) |
| Linear Rebase | git fetch origin && git rebase origin/main |
Places local commits directly on top of remote root without merge commits |
By employing the --allow-unrelated-histories flag or rebasing onto remote branches, you override Git’s default safety check safely, allowing disparate commit histories to merge smoothly.