fatal: refusing to merge unrelated histories

Git's refusal to merge unrelated histories is most commonly encountered with GitHub Pages (gh-pages branch). When you create a gh-pages branch using git checkout --orphan gh-pages, it has no commit history in common with main. Another developer who tries git pull origin gh-pages or merges main changes into gh-pages gets the refusal because the two branches have completely separate ancestry. The --allow-unrelated-histories flag explicitly permits this merge: git merge --allow-unrelated-histories origin/gh-pages. This creates a merge commit that grafts the two independent histories together. Inspect the result with git log --graph --oneline to verify the structure before pushing. A second common trigger: creating a new repository on GitHub with "Initialize with a README" checked, then trying to push a local repository that was initialized separately with git init and already has commits. The GitHub-initialized repo has a commit (the README creation) that shares no ancestor with your local repository. The fix: git pull origin main --allow-unrelated-histories merges the README commit into your local history before pushing. Post-merge, the combined repository history contains two disconnected root commits. This is permanent and visible in git log --oneline --graph. It does not cause any functional issues but surprises contributors who run git log and see two separate commit chains converging at a single merge commit.