Git shows fatal: refusing to merge unrelated histories when you try to merge or pull a branch that has no commit in common with yours. It almost always happens when you create a project locally with git init, create a repository on GitHub with a README or licence, and then try to pull one into the other. The two histories started separately, so Git stops to protect you. If you’re sure they belong together, the fix is git pull origin main --allow-unrelated-histories, then resolve any conflicts and commit.
I reproduced the error in a test repository with Git 2.47.3 on 12 October 2026, using a local “remote” in place of GitHub so every step is visible. All output below is real.
Every Git repository is a chain of commits, each pointing to its parent. When you merge, Git looks for the merge base: the most recent commit both branches share. It compares each side against that base to work out what changed.
When two repositories were created separately, each has its own first commit (a “root” commit) and there is no shared ancestor. You can check this directly with git merge-base:
$ git fetch origin
$ git merge-base HEAD origin/main
$ echo $?
1
No commit printed, and exit code 1: there’s no merge base. Without one, a merge would just glue two unrelated projects together, which is rarely what you meant.
A root commit is a commit with no parent. A normal repository has one. After merging unrelated histories, it has two, and you can list them:
$ git rev-list --max-parents=0 HEAD
afe6969
18c401d
$ git log --oneline --max-parents=0
afe6969 First local commit
18c401d Initial commit
That’s a handy way to confirm what happened, and to spot repositories where unrelated histories were merged in the past.
This wasn’t always an error. The Git 2.9 release notes explain that merging unrelated histories used to be allowed, and that this let “an unnecessary parallel history” get merged into projects by unsuspecting maintainers. From Git 2.9 onwards, git merge refuses by default, with an escape hatch: the --allow-unrelated-histories option.
The official git merge documentation adds that, because merging independent projects is “a very rare occasion, no configuration variable to enable this by default exists or will be added.” You have to opt in each time, on purpose.
origin is the default name for it.Two histories are “unrelated” when they have different root commits and no merge base.
Here’s the common beginner scenario, step by step:
main.git init, add your project files and commit them.origin and try to pull.In my test, the local repository had one commit (“First local commit” with index.php and a README.md), and the remote had its own “Initial commit” with a README.md and LICENSE. With a recent Git, the first git pull doesn’t even get as far as the unrelated-histories check; it asks how to reconcile the branches:
$ git pull origin main
hint: You have divergent branches and need to specify how to reconcile them.
...
fatal: Need to specify how to reconcile divergent branches.
Choosing merge (--no-rebase), or merging the fetched branch directly, produces the error this post is about:
$ git pull --no-rebase origin main
From ../remote
* branch main -> FETCH_HEAD
* [new branch] main -> origin/main
fatal: refusing to merge unrelated histories
$ git merge origin/main
fatal: refusing to merge unrelated histories
If you skip pulling and try to push first, you get a different message that sends you back to pull:
error: failed to push some refs to '../remote.git'
hint: Updates were rejected because the remote contains work that you do not
hint: have locally. This is usually caused by another repository pushing to
hint: the same ref. If you want to integrate the remote changes, use
hint: 'git pull' before pushing again.
If both histories genuinely belong to the same project, tell Git so:
$ git pull --no-rebase origin main --allow-unrelated-histories
From ../remote
* branch main -> FETCH_HEAD
Auto-merging README.md
CONFLICT (add/add): Merge conflict in README.md
Automatic merge failed; fix conflicts and then commit the result.
The --no-rebase makes the pull a merge, so it works whatever your pull.rebase setting is. (git pull passes --allow-unrelated-histories through to git merge; the Git 2.9 notes mention that too.) If you’ve already fetched, git merge origin/main --allow-unrelated-histories does the same thing.
Both sides created a file called README.md, so Git reports an add/add conflict. git status --short shows the state:
A LICENSE
AA README.md
LICENSE only existed on the remote, so it was added cleanly (A). README.md was added on both sides (AA) and contains conflict markers. Open it, keep what you want, delete the <<<<<<<, ======= and >>>>>>> lines, then stage and commit:
$ git add README.md
$ git commit -m "Merge remote main with unrelated history"
$ git log --oneline --graph
* 3c08e61 Merge remote main with unrelated history
|\
| * 18c401d Initial commit
* afe6969 First local commit
The graph shows two root commits joined by a merge commit. From now on, the histories are related, and normal git pull and git push work. In my test, git push origin main succeeded straight after.
If the conflicts look wrong, or you realise you’re merging the wrong repository, stop before committing:
$ git status --short
A LICENSE
AA README.md
A index.php
$ git merge --abort
$ git status --short
$ git log --oneline
da4278f a
git merge --abort returned my test repository to exactly the state before the merge: a clean working tree and only the original commit.
If you prefer a straight-line history without a merge commit, rebase your local commits onto the remote branch:
$ git pull --rebase origin main
Successfully rebased and updated refs/heads/main.
In a second test repository with one local commit, this replayed the commit on top of the remote history without any unrelated-histories error, because rebasing doesn’t need a merge base in the same way. If both sides touch the same file, you’ll resolve conflicts during the rebase instead. Rebasing rewrites your local commits, so only do it with commits you haven’t shared yet.
For a brand-new project, the simplest fix is to avoid the problem:
git clone <url>.In my test, a fresh clone contained the merged history and all three files (LICENSE, README.md, index.php), with no special options needed. If you haven’t made any commits locally that you care about, this is the cleanest route.
.gitignore or licence if you already have a local project. GitHub then shows push instructions and there’s only one history.git remote -v shows where origin points. Pulling from the wrong repository is the one case where this error is saving you from a real mistake.To never see this error, create the GitHub repository empty and push your existing project into it. I tested this sequence against an empty remote:
$ git init
$ git add .
$ git commit -m "First commit"
$ git branch -M main
$ git remote add origin <your-repo-url>
$ git push -u origin main
* [new branch] main -> main
branch 'main' set up to track 'origin/main'.
git branch -M main renames your branch to main in case your Git defaults to master. -u sets up tracking, so afterwards a plain git pull and git push know where to go; git status -sb showed ## main...origin/main. If you’re also adding an AGENTS.md for AI coding tools, my guide on what AGENTS.md is explains what to put in it before that first commit.
Git refuses for a reason. Think twice if:
origin at the wrong repository. Merging would mix two different projects. Fix the URL with git remote set-url origin <correct-url> instead..git and running git init again. The new history is unrelated to the old remote. It’s usually better to clone the remote again and copy your changes in.gh-pages branch, which usually shouldn’t be merged into main.If you merge by mistake and haven’t pushed yet, my guide to undoing the last commit and keeping your changes explains how to step back safely.
Occasionally you really do want to combine independent repositories, for example moving two small projects into one monorepo while keeping their history. The usual approach is:
git remote add other <url>.git fetch other.git merge other/main --allow-unrelated-histories.This is the “two projects that started their lives independently” case the documentation mentions, and it’s what the option exists for.
Once you’ve merged with --allow-unrelated-histories, the merge is permanent history like any other. Everyone who clones the repository gets both root commits and the merge commit joining them. That’s normally harmless, and git log simply shows a little extra history at the start.
Two things are worth knowing. First, tools that walk back to “the first commit” (for example, scripts using git rev-list --max-parents=0 HEAD) will find two. Second, if you merged by mistake and already pushed, undoing it means rewriting shared history, which affects everyone else using the repository. It’s far easier to check git remote -v and the files involved before you merge than to clean up afterwards.
fatal: Need to specify how to reconcile divergent branches. Not the same error, but it often comes first. Choose --no-rebase (merge), --rebase or --ff-only, or set a default with git config pull.rebase false.Updates were rejected because the remote contains work that you do not have locally. Your push was refused because the remote has commits you don’t. Pull first, using one of the fixes above.It means the branch you’re merging or pulling has no commit in common with your current branch. Since Git 2.9, Git refuses such merges by default to stop unrelated projects being combined by accident.
If the histories belong together, run git pull origin main --allow-unrelated-histories (add --no-rebase if Git asks how to reconcile branches). Resolve any conflicts, then git add and git commit.
Ticking “Add a README” makes GitHub create its own first commit. Your local git init project has a separate first commit, so the two histories are unrelated. Creating the GitHub repository empty avoids it.
It’s safe when both histories are really the same project, such as a local project and a new GitHub repository. It’s risky if origin points at the wrong repository, because you’d merge two different projects.
No. The Git documentation says no configuration variable exists or will be added for it, because merging unrelated histories should be rare and deliberate.
It happens when both branches added a file with the same path, such as README.md. Edit the file to keep the content you want, remove the conflict markers, then stage and commit it.
You can. git pull --rebase origin main replays your local commits on top of the remote ones and gives a straight-line history. Only rebase commits you haven’t pushed or shared yet.
// note
This is a learning note from studying the web. It is one small topic, written so I can remember it. It is not a course and not a claim that I have finished the subject.
If a sentence is wrong, say so from the contact page and name this title. Drafts never appear here. Related notes, when they exist, are other published posts, and the same sample rule applies to each of them.
AGENTS.md is a plain Markdown file in your repo that tells AI coding agents how to build, test and work on your project. What it is, which tools read it, what to put in it, nested files, and a tested template with a script that checks its commands.
msconfig opens Windows System Configuration, a built-in troubleshooting tool for controlling how Windows starts. What each tab does, how to do a clean boot, diagnostic startup and safe boot, how to escape a safe mode loop, and why it matters for security.
PHP’s ‘Cannot modify header information – headers already sent’ warning means something was output before header() or session_start(). How to read ‘output started at’, and fixes for spaces, BOMs, echo, closing tags, includes and output buffering. Tested.
From Python 3.15, open() without an encoding uses UTF-8 everywhere, including Windows. What changes, why ‘charmap’ and ‘utf-8’ UnicodeDecodeErrors happen, how to fix them, and how to switch the old behaviour back. Tested.