Git "fatal: refusing to merge unrelated histories": when the flag is safe, and when it isn't

1. Check before you merge

The flag does exactly what you tell it, including merging two projects that have nothing to do with each other. So take a moment to look:

git remote -v
git fetch origin
git log --oneline --all --graph -n 20

You should see two separate lines. Then see what’s in the other side:

git fetch origin
git ls-tree --name-only origin/main
git log --oneline origin/main

Is that what you expected? Just a README.md and a LICENSE is the harmless case. If you see some other project’s files, your remote is wrong. Fix that instead of merging:

git remote set-url origin git@github.com:acme/the-right-repo.git

2. New repository: merge the two

git pull --no-rebase origin main --allow-unrelated-histories

--no-rebase makes the choice explicit. Without it, and with no default set, current versions of Git stop earlier with fatal: Need to specify how to reconcile divergent branches.

If both sides have a file with the same name, such as a README, you’ll get a conflict:

CONFLICT (add/add): Merge conflict in README.md
Automatic merge failed; fix conflicts and then commit the result.

Edit the file to keep what you want, and finish the merge:

git add README.md
git commit
git push -u origin main

Your history now has both starting points, joined by a merge commit. That’s perfectly fine.

3. New repository: throw away the remote’s first commit

If the remote holds nothing you need, such as an auto-generated README, you can replace it. This overwrites the remote, so check that nobody else has pushed there first:

git log --oneline origin/main
git push --force-with-lease origin main

--force-with-lease refuses if the remote has changed since you last fetched, which makes it safer than --force. A protected branch will refuse it anyway, and that’s the correct behavior.

The other way is to start from the remote, which keeps one clean history:

git clone git@github.com:acme/app.git app-clean
rsync -a --exclude .git app/ app-clean/      # your files on top, without the old history

Next time, avoid all of this: create the GitHub repository empty, with no README, license or .gitignore. Or clone first, and work in the clone. The .gitignore Generator can write that file before your first commit.

4. A shallow clone

Here’s one that looks the same with a very different cause. With a shallow clone, the shared commit isn’t on your machine, so Git thinks the histories are unrelated:

git rev-parse --is-shallow-repository

true means this is your case. Don’t use the flag: get the rest of the history instead.

git fetch --unshallow

It’s common in CI, where a checkout usually fetches one commit. For example, in GitHub Actions:

- uses: actions/checkout@v4
  with:
    fetch-depth: 0

5. History was rewritten

Someone rewrote the history with git filter-repo, or recreated the repository to remove a leaked secret. Your copy and the remote now have different commits all the way back. Merging would bring the old history back, including whatever was removed.

So if you have no unpushed work, reset to the new history. This discards your local commits and uncommitted changes:

git status
git fetch origin
git reset --hard origin/main

If you do have local work, save it as a patch before that, with git format-patch origin/main --stdout > my-work.patch, and apply it afterwards. Asking the person who rewrote it is a good idea too.

6. Combining two real projects

If you do want to merge two real repositories, keep them apart by moving one into its own folder first, in the repository you’re merging from:

mkdir legacy-app
git mv -k * legacy-app/
git commit -m "Move everything into legacy-app/"

Then, in the main repository:

git remote add legacy ../legacy-app
git fetch legacy
git merge legacy/main --allow-unrelated-histories

You then have both, with their histories, without conflicts.