Pushing and pulling from a Git repository can either be a lightning-fast click of a couple of arrow keys or a nightmare, when errors occur and your hard work is at risk of being lost forever. Something you may run into is the fatal: refusing to merge unrelated histories error.
This Git error frequently occurs when you’re attempting to merge two repositories that have mismatched commit histories. Usually, it’s one of two things that caused this error:
- Your .git folder has been deleted or corrupted, resulting in the Git to be unaware of your local history and you’re trying to push or pull from the remote depository, or:
- You are trying to pull data from a repository with its own commit history and you attempt to pull from a remote repository.
Your .git folder is a critical part of your bash prompt. It contains all the information needed for version control in your repositories. It’s like a magician’s black hat, but instead of a rabbit, it has your commits, remote repo addresses, branches, and much more.
Image Credit: https://www.educative.io/edpresso/the-fatal-refusing-to-merge-unrelated-histories-git-error
What’s happening under the hood?
When you’re attempting to run a git pull from a remote repo, You’re essentially running a git fetch and a git merge. Without your .git folder, or working with a newly created repository, Git becomes confused and thinks your two projects are unrelated and makes it impossible to pull down from a remote repo. (You might not have cloned the repo, and instead ran a git init which makes git think there are no common commits). Running into this error and handling it incorrectly, can cause you to lose development work or impact your teammates if deliverables are on the line.
A newly created repository from GitHub or Bitbucket usually contains a README file. You’ll frequently run into a “refusing to merge unrelated history” when pulling the repo locally for the first time. The scenario would typically be as follows:
1. Create a local repo
2. Go to your SCM and create the same repo
3. You’ll run into the fatal: refusing to merge unrelated histories error when attempting to pull
The good news is that this is a relatively quick and easy problem to fix.
How do I fix this?
There are a couple of slightly different options, depending on your starting point to fix this Git error. If your .git folder has been deleted or has become corrupt, follow the case #1 solution with an extra step at the beginning to re-create the .git folder. Otherwise, head into the case #2 solution to allow unrelated histories. This will incorporate the changes you’ve made locally to your remote repo.
Note: If using Github, switch out master for main
Case #1 Solution: Deleted or corrupt .git folder
- Delete your .git folder if it exists
- git init
- git pull origin master –allow-unrelated-histories
- git merge origin origin/master (Vim will open here, enter insert mode and save)
- git add .
- git commit -m “<some commit message>”
- git push origin master
Case #2 Solution: Newly Created Repo
- git pull origin master –allow-unrelated-histories
- git merge origin origin/master (Vim will open here, enter insert mode and save)
- git add .
- git commit -m “<some commit message>”
- git push origin master
Now that you’ve merged two unrelated histories, you should be back up and running for your local development work with this simple fix. To avoid this issue going forward, there are a few best practices:
- Create your repos and branches from your SCM tool (Bitbucket / Git). In other words, start in the remote and bring it down locally to work.
- Constantly run pulls if working with others in the same project space.
- When in doubt, re-clone the repo – it’s kind of like restarting your computer.
The post How to Fix the Fatal: Refusing to Merge Unrelated Histories Error
