git pull / git merge fails with 'fatal: refusing to merge unrelated histories' (often right after creating a GitHub repo with a README and pushing an existing local project). How do I fix it safely?

Cause: the two branches you're combining share no common commit. Since Git 2.9, git merge (and git pull, which merges by default) refuses this unless you say it's intended, because it usually means the wrong repository or branch. The most common harmless case: you ran git init locally and committed, then created the remote repository on GitHub/GitLab with a README, license or .gitignore, so the remote has its own separate first commit. Other cases: a shallow clone, a repo whose history was rewritten, or a remote URL that points at the wrong project. How to check: - git remote -v: is the remote really the repo you meant? - git log --oneline origin/main (after git fetch) vs git log --oneline main: if the remote only has an initial README commit, it's the harmless case. - In a shallow clone, git rev-parse --is-shallow-repository prints true. Fix (pick what fits): 1. Harmless case, keep both: git pull origin main --allow-unrelated-histories (or git fetch then git merge origin/main --allow-unrelated-histories). Resolve conflicts in README/.gitignore if any, commit, then git push. 2. The remote only has a throwaway README and you'd rather have your local history alone: after confirming nothing else is there, git push --force-with-lease origin main replaces it. Only do this on a repo nobody else is using. 3. Shallow clone: git fetch --unshallow (or a larger --depth) so Git can find the common commit, then pull again. 4. Wrong remote: fix it with git remote set-url origin <correct-url> instead of forcing the merge. 5. To avoid it next time: create the remote repository empty (no README/license/.gitignore) when you already have a local project, as GitHub's guide for adding local code recommends. Verify: git log --graph --oneline shows a merge (or your history alone after option 2), and git status reports the branch up to date with origin. Sources: https://git-scm.com/docs/git-merge https://git-scm.com/docs/git-pull https://docs.github.com/en/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github