# Fix 'fatal: refusing to merge unrelated histories' in 5 Minutes (Copy-Paste Commands) ## Stay calm — your code is not gone You just hit `fatal: refusing to merge unrelated histories` in the terminal and pasted it straight into the search bar, right? Good news first: **this is not an error that deletes data.** Git is only hitting a safety brake because merging as-is would be risky. Your local code and the remote code are both still intact. In most cases you are in one of these three scenarios: - **①** You created a GitHub repo with README/LICENSE checked, then tried `git pull` for the first time against code you had already been working on locally (the most common case) - **②** You are trying to combine two projects that both have real commit histories - **③** You accidentally deleted the `.git` folder and ran `git init` again, breaking the history If you recognize your situation, scroll down and copy-paste the commands for that branch. ## Why Git blocks it: there is no common ancestor commit One-line definition: **If two branches do not share a common ancestor commit (merge base), Git treats them as "unrelated histories" and refuses to merge.** When you create a repo on GitHub with a README, the remote already has a first commit `B1`. Meanwhile your local repo, after `git init`, independently stacked `A1 → A2`. The two lines of history have completely different starting points. ``` Local (started from a first commit unrelated to origin) A1 ── A2 (main) Remote (started from the README commit GitHub created) B1 (origin/main) ↑ No common ancestor (merge base) connecting the two → Git refuses the merge ``` A normal merge brings back together "two branches that diverged from a common ancestor." When the starting points themselves are different, as above, Git stops and asks, "Are these even the same project? Am I about to merge the wrong repos?" That is why you must explicitly say "yes, force the merge" with `--allow-unrelated-histories`. ## Situation-specific fix branches (copy-paste) ### ① The remote is a practically empty repo with only README/LICENSE This is the most common case. To keep your local code and also bring in the remote README, one line is enough. ```bash git pull origin main --allow-unrelated-histories # Fetch remote main and force-merge with local → then git push ``` > ⚠️ **Warning** > `--allow-unrelated-histories` is an option that **forcibly ties two unrelated histories into one**. If you mistype the URL and run it against the wrong repo, **someone else's project files will be mixed into yours wholesale.** Before you run it, always check that the origin URL is correct with `git remote -v`. If you do not need the remote README and are fine overwriting everything with your local content, a force push without merging is cleaner (note: the remote commit will disappear). ```bash git push -u origin main --force # Discard the remote README commit and overwrite with local ``` ### ② Both sides have real working commits If both lines of history have meaningful commits, I recommend fetching and then merging explicitly using the "safe merge in practice" procedure below. The one-liner (`git pull ... --allow-unrelated-histories`) also works, but because files from both projects get mixed in at once, it is safer to split the steps and inspect as you go. ### ③ You accidentally re-initialized `.git` and broke the history If you want to recover the original history, the proper approach is to restore it from `git reflog` or a backup. If you just need to push the current state to the remote, you can tie the histories together with `--allow-unrelated-histories` the same way as in ②. ## Safe merge in practice: step-by-step This is the proper approach for anyone who finds a one-line copy-paste scary. Comments explain what each step does. ```bash git remote add origin https://github.com/ACCOUNT/repo.git # Connect the remote repository git fetch origin # Fetch remote contents (no merge, inspect only) git merge origin/main --allow-unrelated-histories # Merge after explicitly allowing unrelated histories # (If there are conflicts, see 'Handling conflicts' below) git push -u origin main # Push the merge result to remote and set upstream tracking ``` Splitting into `fetch` → `merge` lets you visually inspect what is on the remote with `git log origin/main` before merging, which reduces accidents. > 💡 **Practical tip (from experience)**: When I merge a new repo, I always start with `git fetch`. I once handled it with a one-line `git pull`, got a README conflict plus someone else's .gitignore mixed in, and lost 30 minutes. My conclusion: "copy-paste is fast, but fetch is safe." ## Conflict handling flow If both sides have a README.md, you will almost certainly see a message like this on merge. ``` CONFLICT (add/add): Merge conflict in README.md Automatic merge failed; fix conflicts and then commit the result. ``` Don't panic—handle it in order. ```bash git status # Check the list of conflicted files (shown as both modified) # Open README.md in an editor and clean up the <<<<<<< ======= >>>>>>> markers git add README.md # Mark as resolved git commit # Finish with the merge commit ``` Keep only the content you want between `<<<<<<<` (your changes) and `>>>>>>>` (remote changes), and delete the markers. If more complex conflicts or rebase conflicts confuse you, see the separate post **'Resolving git rebase conflicts'** (internal blog link). ## Undoing a bad merge If things got mixed up the wrong way, you can undo it immediately. ```bash # Method 1: If it was right after the merge, recover with one line git reset --hard ORIG_HEAD ``` `ORIG_HEAD` is a pointer Git automatically remembers for the position just before a dangerous operation such as a merge or reset. So if you are right after the merge, this one line cleanly restores the previous state. ```bash # Method 2: If you have already done other work, find the previous commit with reflog git reflog # Check every HEAD movement git reset --hard # Return to the desired point ``` `reflog` is a safety net that records "every position you have been through," including ones that do not show up in a normal `git log`. Even a commit you reset or merged by mistake can be restored if you know the hash. ## Checklist so you never see this error again - When creating a new repo on GitHub, **do not check** README/LICENSE/.gitignore—create a completely empty repo - Push your local code to that empty repo for the first time with `git remote add` → `git push -u origin main` (this naturally creates a common ancestor, so the error never appears) - If you really need a README, create it locally and include it in the first commit GitHub recommending auto-adding a README when creating a repo has caused this error to explode among beginners. Remember "empty repo first, files from local" and you will prevent most cases. ## Frequently asked questions (FAQ) **Q1. I passed the option but it still refuses.** A. Almost certainly a branch-name typo. Check whether the remote default branch is `main` or `master` with `git branch -r`. Default branch names changed from `master`→`main`, so if you copy an old example that still says `master`, you will point at the wrong branch and fail. **Q2. It says `master`, not `main`.** A. Replace every `main` in the commands with `master`. Or unify the local branch name with `git branch -M main` and then proceed. **Q3. I omitted the branch name and got a different error.** A. If you omit the branch like `git pull origin --allow-unrelated-histories`, you get a separate error meaning "I don't know which branch to fetch." Always specify the branch name, as in `git pull origin main ...`. This is a different cause from the unrelated histories problem.

#allow-unrelated-histories

How to Fix 'fatal: refusing to merge unrelated histories' (Copy-Paste Commands)