This error occurs when Git detects that two branches or repositories have no common commit history. Git refuses the merge by default to prevent accidentally combining unrelated projects.
When you see the error "fatal: refusing to merge unrelated histories", Git is telling you that it cannot find a common ancestor commit between the branches you are trying to merge. This safety mechanism was introduced in Git 2.9 to prevent users from accidentally merging two completely separate projects. In Git, branches are expected to share a common starting point in their history. When two branches have completely independent commit histories with no shared commits, Git considers them "unrelated" and blocks the merge operation to protect against unintended repository corruption or confusion. This commonly happens when you create a new local repository, make some commits, and then try to pull from a remote repository that was initialized separately. It can also occur if the .git directory was corrupted or deleted, breaking the historical connection between your local and remote repositories.
If you are trying to pull from a remote repository and encounter this error, add the --allow-unrelated-histories flag:
git pull origin main --allow-unrelated-historiesReplace main with your target branch name (e.g., master). This tells Git to proceed with the merge even though the branches have no common history. You may need to resolve merge conflicts after running this command.
If you are merging a local branch, use the flag with the merge command:
git merge <branch-name> --allow-unrelated-historiesFor example, to merge a branch called feature into your current branch:
git merge feature --allow-unrelated-historiesGit will create a merge commit that combines both unrelated histories into one unified history.
After allowing unrelated histories, Git will attempt to merge the files. If there are conflicting changes, you need to resolve them:
# Check which files have conflicts
git status
# Open conflicting files and resolve the conflicts manually
# Look for conflict markers: <<<<<<<, =======, >>>>>>>
# After resolving, stage the files
git add <resolved-file>
# Complete the merge
git commit -m "Merge unrelated histories"If the error is caused by a shallow clone that does not have enough history, fetch the complete repository history:
git fetch --unshallowThis converts your shallow clone into a complete clone with full history, which may resolve the unrelated histories error.
If the above solutions do not work or you want a cleaner approach, you can clone the remote repository fresh and copy your changes:
# Backup your current work
cp -r my-project my-project-backup
# Clone the remote repository
git clone <remote-url> my-project-new
# Copy your changed files to the new clone (excluding .git)
rsync -av --exclude='.git' my-project-backup/ my-project-new/
# Stage and commit your changes
cd my-project-new
git add .
git commit -m "Add local changes"Understanding the flag:
The --allow-unrelated-histories flag was introduced in Git 2.9. In earlier versions of Git, merging unrelated histories was allowed by default, which sometimes led to confusion when users accidentally merged unrelated projects.
When NOT to use this flag:
- If you are genuinely working with unrelated projects that should remain separate
- If you suspect your repository was compromised or tampered with
- If you are unsure why the histories are unrelated - investigate first
Prevention strategies:
1. Always clone an existing remote repository before starting work, rather than initializing locally and connecting later
2. When creating a new repository on GitHub, do not initialize with a README if you plan to push an existing local repository
3. Avoid using --depth in clones unless you understand the limitations
4. Keep backups of your .git directory for important repositories
Rebase with unrelated histories:
For rebase operations, you can use:
git rebase <branch> --allow-unrelated-historiesHowever, be cautious with rebase as it rewrites commit history and can cause issues if others are working on the same branch.
kex_exchange_identification: Connection closed by remote host
Connection closed by remote host when connecting to Git server
fatal: unable to access: Proxy auto-configuration failed
How to fix 'Proxy auto-configuration failed' in Git
fatal: unable to access: Authentication failed (proxy requires basic auth)
How to fix 'Authentication failed (proxy requires basic auth)' in Git
fatal: unable to access: no_proxy configuration not working
How to fix 'no_proxy configuration not working' in Git
fatal: unable to read tree object in treeless clone
How to fix 'unable to read tree object in treeless clone' in Git