Troubleshooting

fatal: refusing to merge unrelated histories? Why Git says it and how to fix it

Git refuses to merge unrelated histories when two repos share no commit. Fix it with git pull --allow-unrelated-histories, a rebase or a fresh clone.

Published ~8 min read
On this page

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.

bash
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 main

The 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 init and committed in your project folder. Then git remote add origin ... and git pull origin main.
  • Someone deleted .git and ran git init again, 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:

output · git 2.39.5
$ 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:

output · git 2.39.5
$ 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 histories

A 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:

output · git 2.39.5
$ 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 commit

Run 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.

  1. 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 LICENSE and app.py) are taken as they are. A file both sides created with different content becomes an add/add conflict.

  2. 2Resolve the conflicts
    output · git 2.39.5
    $ git status --short
    A  LICENSE
    AA README.md
    $ cat README.md
    <<<<<<< HEAD
    # my app
    =======
    # demo
    >>>>>>> 5744ee41cf9aa8ffba4f722b0cb27d98144f9dcb

    Edit the file to the content you want, remove the marker lines, then git add README.md. To keep one side whole, use git checkout --ours README.md (your version) or git checkout --theirs README.md (the remote's), then git add.

  3. 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 -> main

    The 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:

output · git 2.39.5
$ 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 commit

Your 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:

bash
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 main

rsync 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:

output · git 2.39.5
$ 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.go

git 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):

output · git 2.39.5
$ 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

SituationFixRewrites history?
Remote has a generated README or LICENSE, local has your codegit pull --rebase origin mainLocal commits only
Both sides have real work to keepgit pull --no-rebase origin main --allow-unrelated-historiesNo
Local history is not worth keepingClone the remote, copy files in, commitNo
Remote content is disposable and unsharedgit push --force-with-lease origin mainYes, on the remote
Two separate projects become one repositorygit subtree add --prefix=dirNo
Wrong remote URL or branchFix the remote, do not add the flagNo

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.

Related articles

All troubleshooting

git: command not found? Install Git on any Linux

Git is not installed. Fix: sudo apt install git (Debian, Ubuntu), apk add git (Alpine), xcode-select --install (macOS), winget install Git.Git (Windows).

How to rename a Git branch: local, remote, and master to main

Git rename branch: git branch -m old new renames it locally. Then push the new name, delete the old one on the remote, update clones, move master to main.

How to create a new branch in Git: git switch -c, git checkout -b and git push -u

How to create a new branch in Git with git switch -c or checkout -b, from a tag or remote branch, push it with -u, delete it, and install Git on Ubuntu.

Permission denied (publickey): every reason SSH rejects your key

The SSH connected but your key was refused. The four causes: wrong user, wrong key offered, bad file permissions, or the key was never installed.

rsync command: examples for SSH, exclude, --delete, progress and dry run

rsync -av SOURCE/ DEST/ copies a folder and later sends only changes; a slash on the source copies its contents. Examples for SSH, exclude, --delete, dry run.

fatal: not a git repository? Why Git cannot find .git and how to fix it

fatal: not a git repository means Git found no .git here or in any parent folder. Fix the folder, a broken .git, worktrees, mounts, cron and Docker.

error: failed to push some refs: every cause and the fix for each

Git failed to push some refs: read the reason line. Fixes for rejected fetch first, non-fast-forward, src refspec main, hooks and protected branches.