Fix: fatal: refusing to merge unrelated histories

Git merges by finding a commit both sides have in common. When there is none, Git assumes something is wrong and stops:

$ git pull --no-rebase origin main
 * branch            main       -> FETCH_HEAD
fatal: refusing to merge unrelated histories

Why it happens

The classic case: you ran git init and committed a project on your computer, then created a repository on GitHub and ticked “Add a README” (or a license or .gitignore). GitHub made its own first commit. Now there are two separate histories with no shared starting point.

Other causes are pointing origin at the wrong repository, or a remote whose history was rewritten from scratch. Check the URL first:

git remote -v

If the URL is wrong, fix it with git remote set-url origin <correct-url> and stop here. Do not force two unrelated projects together.

Fix: allow the merge once

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

Git now merges the two histories. If both sides have a file with the same name, typically README.md, you get a conflict:

CONFLICT (add/add): Merge conflict in README.md

Edit the file, keep what you want, remove the conflict markers, then finish:

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

The flag is needed only for this first merge. Afterwards the histories are connected and normal pulls work.

Alternative: replay your commits on top

git pull --rebase origin main takes your local commits and replays them on top of the remote’s history, which gives one straight line instead of a merge commit. It does not need the flag. Any same-name file still conflicts; fix it, git add, and git rebase --continue.

Alternative: the remote has nothing you need

If the GitHub repository only contains an auto-generated README and you are certain nobody else has pushed to it, you can replace its history with yours:

git push --force-with-lease origin main

This deletes the remote’s commits. Never do it on a repository other people use.

Avoid it next time

• Already have a local project? Create the GitHub repository empty: no README, license, or .gitignore. Then add the remote and push.
• Starting fresh? Create the repository on GitHub with a README first, then git clone it and work inside the clone.
• With the GitHub CLI, gh repo create run inside an existing project can create the remote from it directly.