Fix Git refusing to merge unrelated histories

fatal: refusing to merge unrelated histories means Git could not find a common ancestor for the histories being merged. A typical cause is creating a local repository with git init while separately initializing the remote with a README.

First confirm that both histories belong in the same repository. If they do, merge with --allow-unrelated-histories. This is a merge option, not a git rebase option.

Fetch, inspect, and merge explicitly

If you have not configured the remote, add the correct URL first:

git remote add origin git@github.com:OWNER/REPOSITORY.git

If origin already exists, inspect it instead of adding it again:

git remote -v
git fetch origin
git log --oneline --graph --all
git merge --allow-unrelated-histories origin/main

Run the merge on the local branch that should receive the remote history, with a clean working tree. If both sides added README.md, resolve that conflict deliberately, stage the resolved file, and finish:

git add README.md
git merge --continue

Use git merge --abort to abandon an unfinished merge. After review, push the intended branch, for example git push -u origin main when your local branch is main.

The equivalent pull form must explicitly select merging if your configuration normally rebases:

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

For another local project branch, use git merge --allow-unrelated-histories other-branch.

Alternatives when one history is disposable

If the remote has only a starter README and you do not need to preserve the local commits, clone the remote into a new directory and copy the project files into it. Exclude the old .git directory, credentials, and generated output. Review and commit the copied files normally. Keep the original clone until you have verified the result.

Conversely, replacing the remote starter history can be appropriate if it contains no work you need to keep. That is a history rewrite: confirm the remote tip, coordinate with collaborators, and use a scoped explicit lease rather than a blind git push -f.

FAQ

How can I check for a common ancestor?

git merge-base main other-branch

An exit status of 1 with no commit output means no merge base was found; invalid refs produce a different error. In a shallow clone, missing history can also prevent finding an ancestor. Check git rev-parse --is-shallow-repository and fetch the needed history before deciding the projects are unrelated.

What does allowing unrelated histories change?

The merge creates a connection between previously separate roots. Both histories remain reachable through the resulting merge commit. It does not establish that the remote was correct or that overlapping files were combined sensibly.

What if I see this during a rebase workflow?

Identify which command actually invoked a merge, including an alias or pull configuration. git rebase main --allow-unrelated-histories is invalid. Deliberately replaying an entire independent history onto another branch requires a separate rebase plan, such as a reviewed root rebase; it is not the same as preserving both roots with a merge.

See git-merge, git-pull, and git-rebase.