Short answer: Git prints fatal: refusing to merge unrelated histories when your branch and the branch you pull or merge have no commit in common, typically because you ran git init locally while the remote already had its own first commit (a README or LICENSE created on GitHub). If both histories really belong together, merge them once with --allow-unrelated-histories, resolve any conflicts, commit and push.
git pull --no-rebase origin main --allow-unrelated-histories
git status # files marked AA need a hand merge
git add README.md # after fixing the conflict markers
git commit --no-edit
git push origin mainThe flag is a one time switch: after that merge the two histories share a commit, and every later git pull works without it. The rest of this page shows the error as it appears in a real repository, how to confirm the cause with git merge-base, and the other ways out: a rebase, a fresh clone, a force push, or merging a second project into a subfolder.
Why Git refuses since version 2.9
Every Git history starts with a root commit. Two repositories created with separate git init runs have two different root commits, so no commit is an ancestor of both. Before Git 2.9 a merge of such histories just went through. The Git 2.9 release notes list it under backward compatibility: merging two branches that have no common ancestor with git merge "is by default forbidden now", to prevent such an unusual merge by mistake. The same release taught git pull to pass --allow-unrelated-histories on to git merge.
The git merge documentation calls the option an override for "histories of two projects that started their lives independently" and says no configuration variable to enable it by default exists or will be added. You pass it on the command line each time you need it, which is rarely. The usual causes:
- You created a repository on GitHub, GitLab or Gitea with "Initialize with README" (or a licence or .gitignore), and separately ran
git initand committed in your project folder. Thengit remote add origin ...andgit pull origin main. - Someone deleted
.gitand rangit initagain, so the local copy got a new root commit while the remote still has the old history. - You pulled the wrong remote or branch, for example another project's repository. Here the refusal is protecting you: do not add the flag, fix the URL.
- You really want to combine two separate repositories into one.
The error, reproduced with Git 2.39.5
We reproduced the first case in a scratch folder on a Debian 12 server with its packaged git version 2.39.5. A bare repository (../remote.git) stands in for GitHub and holds one commit with README.md and LICENSE. The local project was created with git init -b main and has its own first commit with app.py and a different README.md. With no pull.rebase setting, the first pull stops before it even tries to merge:
$ git remote add origin ../remote.git
$ git pull origin main
From ../remote
* branch main -> FETCH_HEAD
* [new branch] main -> 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 a merge with --no-rebase (or git merge origin/main, now that the fetch is done) brings up the real reason. Both commands exit with status 128:
$ git pull --no-rebase origin main
From ../remote
* branch main -> FETCH_HEAD
fatal: refusing to merge unrelated histories
$ git merge origin/main
fatal: refusing to merge unrelated historiesA plain git push origin main from a second unrelated repository is rejected too, with ! [rejected] main -> main (fetch first) and the hint to integrate the remote changes first. That is the same problem seen from the other side.
Confirm it: git merge-base prints nothing
git merge-base prints the best common ancestor of two commits. For unrelated histories there is none. In our repository it printed nothing and exited with status 1; after the fix below it printed the remote's first commit and exited with 0:
$ git merge-base main origin/main; echo "exit=$?"
exit=1
$ git log --oneline --max-parents=0 main origin/main
4ac8b13 first local commit
5744ee4 Initial commitRun it after a fetch, so origin/main exists. The second command lists only root commits (commits without a parent): two of them mean two separate histories. A plain git log --graph does not show this, it draws the two root commits one under the other like parent and child. Also check that the branch names match: GitHub creates main, while git init in Git 2.x names the first branch master unless init.defaultBranch is set. In that case rename the local branch before you merge, so you do not end up with two branches on the remote.
Fix 1: merge once with --allow-unrelated-histories
Use this when both sides hold work you want to keep. The merge commit ties the two root commits together.
- 1Pull with the flag
output · git 2.39.5 $ 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.Files that exist only on one side (here
LICENSEandapp.py) are taken as they are. A file both sides created with different content becomes an add/add conflict. - 2Resolve the conflicts
output · git 2.39.5 $ git status --short A LICENSE AA README.md $ cat README.md <<<<<<< HEAD # my app ======= # demo >>>>>>> 5744ee41cf9aa8ffba4f722b0cb27d98144f9dcbEdit the file to the content you want, remove the marker lines, then
git add README.md. To keep one side whole, usegit checkout --ours README.md(your version) orgit checkout --theirs README.md(the remote's), thengit add. - 3Commit and push
output · git 2.39.5 $ git commit -q --no-edit $ git log --oneline --graph * cc2825c Merge branch 'main' of ../remote |\ | * 5744ee4 Initial commit * 4ac8b13 first local commit $ git push origin main To ../remote.git 5744ee4..cc2825c main -> mainThe push is a normal fast forward for the remote, no force needed. If it fails with an SSH error instead, see Permission denied (publickey).
Fix 2: git pull --rebase gives a straight history
A rebase does not need the flag. It does not look for a merge base to join two histories; it replays your local commits one by one on top of the remote branch. In a second scratch repository (remote with only README.md, local with only app.py), Git 2.39.5 did this without any complaint:
$ git pull --rebase origin main
From ../remote
* branch main -> FETCH_HEAD
* [new branch] main -> origin/main
Successfully rebased and updated refs/heads/main.
$ git log --oneline --graph --all
* 9637612 add app
* 76d0dfe Initial commitYour old root commit is gone: its changes now sit in a new commit on top of the remote's. That is fine while your local commits were never pushed or shared. When a file exists on both sides, the rebase stops with an add/add conflict instead: fix the file, git add it and run git rebase --continue, or leave with git rebase --abort.
Fix 3: clone fresh, or force push a disposable remote
Clone and copy. If the remote only holds a generated README and your local history is not worth keeping, start from the remote and bring your files over without the old .git folder:
git clone git@github.com:you/project.git project-new
rsync -a --exclude .git ./project/ ./project-new/
cd project-new && git add -A && git commit -m "Import project files"
git push origin mainrsync with --exclude is explained in the rsync guide; cp -a works too if you delete the copied .git folder afterwards.
Force push. git push --force origin main replaces the remote branch with your local one, and the remote's commits disappear from that branch.
On a VPS: the same error appears when a site was deployed by running git init and a commit directly in the web root on the server, and that folder later gets the real repository as its remote. If the server has no changes of its own, clone the repository into a new folder and switch the web root to it instead of merging the two histories.
Merging another repository into a subfolder
To combine two real projects without mixing their files, put the second one in its own directory. The Git howto "How to use the subtree merge strategy" does it with an ours merge, which records the other history but keeps your tree, followed by git read-tree with a prefix. We ran it with a docs repository merged into an app repository:
$ git remote add docs ../docs && git fetch -q docs
$ git merge -s ours --no-commit --allow-unrelated-histories docs/main
Automatic merge went well; stopped before committing as requested
$ git read-tree --prefix=docs/ -u docs/main
$ git commit -q -m "Merge docs repo into docs/"
$ git ls-files
docs/index.md
main.gogit subtree add does the same in one command and needs no flag. On our Debian 12 host it came with the git package itself (/usr/lib/git-core/git-subtree):
$ git subtree add --prefix=docs ../docs main
git fetch ../docs main
From ../docs
* branch main -> FETCH_HEAD
Added dir 'docs'Either way the full history of the second project stays reachable from the merge commit. If you only want its files, copy them in and commit instead.
Which fix to use
| Situation | Fix | Rewrites history? |
|---|---|---|
| Remote has a generated README or LICENSE, local has your code | git pull --rebase origin main | Local commits only |
| Both sides have real work to keep | git pull --no-rebase origin main --allow-unrelated-histories | No |
| Local history is not worth keeping | Clone the remote, copy files in, commit | No |
| Remote content is disposable and unshared | git push --force-with-lease origin main | Yes, on the remote |
| Two separate projects become one repository | git subtree add --prefix=dir | No |
| Wrong remote URL or branch | Fix the remote, do not add the flag | No |
Once the histories are joined, branching works as usual: see how to create a branch in Git. If the shell does not know git at all on a fresh server, start with git: command not found.
Frequently asked
Is --allow-unrelated-histories safe to use?
Yes, it only lifts the check for a common ancestor; the merge itself is a normal merge you can inspect, abort with git merge --abort or undo before pushing. Use it once, when you know both histories belong together, such as a local project and a new GitHub repository with a README. If you pulled the wrong remote, fix the URL instead of adding the flag.
Why does git pull --rebase not show the unrelated histories error?
A rebase does not join two histories with a merge commit. It replays your local commits one by one on top of the remote branch, so no common ancestor is needed. In our test with Git 2.39.5 it finished without the flag and left a straight history; a file that exists on both sides still stops it with an add/add conflict.
Can I set allow-unrelated-histories in git config?
No. The git merge documentation says no configuration variable to enable it by default exists or will be added, because merging unrelated histories is meant to be rare. Pass --allow-unrelated-histories on the git merge or git pull command line each time you need it.
What does fatal: not a git repository (or any of the parent directories): .git mean?
You ran a git command in a folder that is not inside a repository: Git found no .git directory there or in any parent folder, and exits with status 128. Change into the project folder with cd, or create a repository with git init or git clone first. It is a different problem from unrelated histories, which needs two existing repositories.