Skip to main content

Fix Git refusing to merge unrelated histories

· 4 min read
Serhii Hrekov
Serhii Hrekov
software engineer, creator, artist, programmer, projects founder

The "refusing to merge unrelated histories" error occurs when you try to merge two branches that do not share a common history. This typically happens when you initialize a new Git repository and then try to pull a remote repository's contents into it, as Git sees them as two completely separate projects.

To solve this, you can use the --allow-unrelated-histories flag. This flag forces Git to merge the two independent histories, creating a merge commit that joins them together.

The Cause of the Error​

Imagine this scenario:

  1. You create a new local repository with git init. This repository has its own unique, initial commit.
  2. You then add a remote URL from an existing GitHub repository and try to pull its contents with git pull origin main.

Because the GitHub repository has its own history, and your new local repository has its own, Git sees them as "unrelated." Git refuses to merge them by default to prevent you from accidentally overwriting your work.

The Solution: Use --allow-unrelated-histories​

You can use the --allow-unrelated-histories flag with the git pull command to force the merge.

  1. Run the Pull Command with the Flag:

    git pull origin main --allow-unrelated-histories

    This will perform a merge, creating a new merge commit that links the two histories together.

  2. Resolve Conflicts (if any): If there are any files with the same name in both repositories, Git will stop the merge and prompt you to resolve the conflicts.

    • Open the conflicting files and manually choose which content to keep.
    • Stage the resolved files with git add ..
    • Complete the merge with git commit.

After this, your local repository will be synchronized with the remote, and you can push your changes as usual.

A Note on Alternative Solutions​

While --allow-unrelated-histories is the most direct solution, some users may consider other methods depending on their goal:

  • Forcing the Remote into the Local Repository: If you don't care about your local history and just want the remote's files, you can simply force-push. This will overwrite the remote repository's history and should be done with extreme caution.

    git push origin main --force

    This approach is highly discouraged in collaborative environments (1).

  • Cloning Instead of Pulling: The best practice is to clone a remote repository instead of initializing a new local one and then pulling. Cloning automatically copies the remote's history and sets up the local repository correctly.

    git clone https://github.com/user/repo.git

By understanding the cause of this error and using the correct flag, you can safely integrate two previously separate repositories.

Sources​

  1. Git Push