Git says 'refusing to merge unrelated histories'? Here's why
Short answer: Git shows "fatal: refusing to merge unrelated histories" when you try to combine two sets of commits that have no commit in common. The most common cause is creating a new repository online with a README or licence file, then trying to pull or push a project you already had on your computer. Git treats them as two separate projects and won't join them without being told. You can merge them once with --allow-unrelated-histories, replace the remote with your local history if the remote only holds starter files, or start again with an empty remote.
Why Git refuses
Every commit in Git points back to its parent, so normal branches share a common ancestor somewhere in their history. That shared point is how Git works out what changed on each side when it merges.
When you create a repository on a hosting site and tick "Add a README", the site makes a first commit containing that file. Your local project has its own first commit, made on your laptop. The two histories start from different roots. Git's documentation says that by default git merge refuses to merge histories that do not share a common ancestor, and that the override exists for "two projects that started their lives independently". Because that is rare, Git deliberately offers no setting to switch the check off permanently.
git pull runs into the same rule, because a pull is a fetch followed by a merge or rebase.
How people usually hit it
- Creating a repository with a README, licence or
.gitignore, then runninggit pull origin mainfrom an existing project. - Pushing first, seeing the push rejected because the remote has commits you don't have, then pulling and getting the unrelated-histories error.
- Rebuilding a project folder from scratch, running
git initagain, and connecting it to the old remote. - Combining an old website repository with a new one created from a template.
GitHub's own guide to adding a local project avoids the problem by telling you not to initialise the new repository with README, licence or gitignore files, and to add them after your first push.
Fix 1: merge both histories (keeps everything)
If the remote has anything you want to keep, merge it in once:
git pull origin main --allow-unrelated-histories
Git creates a merge commit joining the two roots. If both sides have a file with the same name, typically README.md or .gitignore, you'll get a conflict to resolve. Open the file, keep the content you want, then git add it and commit. After that, a normal git push works and future pulls behave as usual because the histories are now connected.
This is the safest choice when you're not sure what's on the remote, or when other people may already have pushed to it.
Fix 2: replace the remote (only if it holds nothing you need)
If the remote contains only the files the hosting site generated and nobody else has used it, you can overwrite it with your local history:
git push --force-with-lease origin main
--force-with-lease is safer than a plain --force, because it refuses to overwrite the remote if it has changed since your last fetch. Before you do this, look at the remote in the browser and confirm there's nothing there except the starter files. If branch protection is switched on for main, the push will be blocked, which is a good sign that protection works; turn it on after this first push instead.
Fix 3: start the remote again
If you're early in a project, deleting the new remote repository and creating it again with no README or licence is perfectly reasonable. Then add the remote and push as normal. This avoids a merge commit you don't need and keeps the history tidy.
When you should stop and think
The override is safe for the README case, but the error is sometimes a warning sign:
- You pointed at the wrong remote. If you copied the wrong URL, merging unrelated histories would pull a different project into yours. Check with
git remote -vfirst. - You re-ran
git initin a folder that already had history elsewhere. Clone the real repository instead and copy your changed files across. - You really are combining two projects. If you want one repository to hold two previously separate codebases, consider bringing the second into its own subfolder so the files don't collide, and agree with your team before rewriting anything shared.
Preventing it next time
Make it a habit when connecting existing code to a new repository:
- Create the remote repository empty.
- Add the remote with
git remote add origin <url>. - Push your branch with
git push -u origin main. - Add a README, licence and
.gitignorelocally, commit and push.
If a client or colleague creates repositories for you, ask them to leave the starter-file boxes unticked.
An illustrative example
A developer building an online shop for a Bristol bakery has the project on their laptop with a few weeks of commits. The bakery's owner creates a repository on the company account with a README and invites them. The developer's git pull fails with the unrelated-histories error. They check git remote -v, confirm the URL is the bakery's new repository, run the pull with --allow-unrelated-histories, keep the owner's README text above their own setup notes, commit, and push. The history now shows the owner's first commit and their own work joined by one merge.
FAQ
Will --allow-unrelated-histories delete anything?
No. It joins both histories with a merge commit. You may need to resolve conflicts in files that exist on both sides.
Can I set Git to always allow this?
No. Git's documentation says no configuration option exists for it, because it should be a rare, deliberate choice.
Why didn't git push just work?
The remote had a commit your local branch didn't contain, so Git rejected the push to avoid losing it.
Does rebasing avoid the merge commit?
It can, but rebasing your commits onto the remote's starter commit rewrites them. For a one-off README, a single merge is simpler.
If your repositories are tangled after a move between computers or accounts and you want them sorted out safely, tell us what you're trying to combine.