{"id":39,"date":"2026-07-15T00:00:00","date_gmt":"2026-07-15T00:00:00","guid":{"rendered":"http:\/\/\/var\/www\/html\/?p=39"},"modified":"2026-07-21T01:02:32","modified_gmt":"2026-07-21T01:02:32","slug":"git-command-line-fatal-refusing-to-merge-unrelated-histories-on-ubuntu-2004-lts","status":"publish","type":"post","link":"https:\/\/butitworkedlocal.com\/git-command-line-fatal-refusing-to-merge-unrelated-histories-on-ubuntu-2004-lts\/","title":{"rendered":"Resolving Git ‘fatal: refusing to merge unrelated histories’ on Ubuntu 20.04 LTS"},"content":{"rendered":"\n

Fix the Git 'refusing to merge unrelated histories' error when pulling or merging disparate repositories on Ubuntu 20.04. Learn the root cause and resolution.<\/strong><\/p>\n\n\n

This guide addresses a common Git error encountered by developers and system administrators on Ubuntu 20.04 LTS servers: "fatal: refusing to merge unrelated histories". This error typically arises when attempting to merge or pull changes from a remote repository into a local one that Git deems to have no common ancestral commits. While seemingly a blocking issue, Git provides a clear mechanism to resolve it, ensuring your project histories can be aligned.<\/p>\n

Symptom & Error Signature<\/h3>\n

When you attempt to integrate changes from a remote Git repository into your local working copy, typically using git pull<\/code> or git merge<\/code>, you might encounter the following error message in your terminal:<\/p>\n

$ git pull origin main\nFrom github.com:your-organization\/your-repository\n * branch            main       -> FETCH_HEAD\nfatal: refusing to merge unrelated histories\n<\/code><\/pre>\n
Or, if you're trying a direct merge:<\/p>\n
$ git merge origin\/main\nfatal: refusing to merge unrelated histories\n<\/code><\/pre>\n
This error halts the pull\/merge operation, leaving your local repository in its current state without integrating the remote changes.<\/p>\n
Root Cause Analysis<\/h3>\n
The "fatal: refusing to merge unrelated histories" error is a safety mechanism introduced in Git version 2.9 (released June 2016). Prior to this version, Git would attempt to merge any two branches you specified, even if they had no common commit history, potentially leading to a confusing and possibly destructive merge.<\/p>\n
Git's core principle is to build a directed acyclic graph (DAG) of commits. When you try to merge two branches, Git normally expects to find a common ancestor commit from which both branches diverged. If no such common ancestor exists, Git considers their histories "unrelated."<\/p>\n
Common scenarios that lead to unrelated histories include:<\/p>\n
    \n
  1. Initializing an Empty Local Repo, Pulling from Existing Remote<\/strong>: You create a new project directory, run git init<\/code>, and then try to git pull<\/code> from an existing remote repository that already has commits (e.g., a README.md<\/code> or initial project files). Your local HEAD<\/code> has no commits, and the remote HEAD<\/code> has a history, so they don't share a common ancestor.<\/li>\n
  2. Remote Repository Initialized Separately<\/strong>: You create an empty repository on a platform like GitHub or GitLab, and then initialize it directly on the web interface<\/em> by adding a README.md<\/code>, .gitignore<\/code>, or license file. Simultaneously, you create a local repository with git init<\/code> and some initial commits without<\/em> cloning the remote. When you later try to git pull<\/code> from the remote into your local repo, their histories are unrelated.<\/li>\n
  3. Restoring from a "Working Directory" Backup<\/strong>: If you only backed up the .git<\/code> folder along with the working directory, and then restored it, or if you only backed up the working directory and then re-initialized Git with git init<\/code>, the new local .git<\/code> history might not align with the remote's history graph if not handled carefully.<\/li>\n
  4. Accidental Parallel Development<\/strong>: Two separate projects were started, both initialized as Git repositories, and later an attempt is made to merge them as if they were branches of a single project.<\/li>\n<\/ol>\n
    In essence, Git is preventing what it perceives as an attempt to merge two entirely distinct timelines, which could obscure project history or introduce unexpected changes.<\/p>\n
    Step-by-Step Resolution<\/h3>\n
    The primary and recommended solution involves explicitly telling Git to allow merging of unrelated histories using the --allow-unrelated-histories<\/code> flag.<\/p>\n
    1. Understanding the allow-unrelated-histories<\/code> Flag<\/h4>\n
    This flag instructs Git to proceed with the merge even if it cannot find a common ancestor between the two histories. When this flag is used, Git treats the first commit of one history and the first commit of the other history as their common base for the merge, effectively creating a merge commit that bridges the two distinct histories.<\/p>\n
    Use this flag with caution. While it resolves the immediate error, ensure you understand why<\/em> the histories are unrelated. This action cannot be easily undone without rewriting history, which can be problematic in collaborative environments.<\/p>\n<\/blockquote>\n
    2. Safely Merging Unrelated Histories (Recommended Approach)<\/h4>\n
    This method preserves both local and remote histories, combining them into a new merge commit.<\/p>\n
    2.1 Verify Current Status and Remote Configuration<\/h5>\n
    Before proceeding, ensure your local repository is clean and correctly configured to point to the remote.<\/p>\n
    # Check for any uncommitted local changes (commit or stash them if necessary)\ngit status\n\n# Verify your remote configuration\ngit remote -v\n<\/code><\/pre>\n
    Expected output for git remote -v<\/code>:<\/p>\n
    origin  https:\/\/github.com\/your-organization\/your-repository.git (fetch)\norigin  https:\/\/github.com\/your-organization\/your-repository.git (push)\n<\/code><\/pre>\n
    2.2 Fetch Remote Changes (Optional, but Good Practice)<\/h5>\n
    It's often good practice to first fetch all remote changes without merging them. This allows you to inspect the remote's history if needed.<\/p>\n
    git fetch origin\n<\/code><\/pre>\n
    2.3 Perform the Merge with --allow-unrelated-histories<\/code><\/h5>\n
    Now, execute the git pull<\/code> or git merge<\/code> command with the crucial flag. Assuming you want to pull from the main<\/code> branch of your origin<\/code> remote:<\/p>\n
    git pull origin main --allow-unrelated-histories\n<\/code><\/pre>\n
    If you prefer to fetch<\/code> and then merge<\/code> manually:<\/p>\n
    git merge origin\/main --allow-unrelated-histories\n<\/code><\/pre>\n
    Git will then attempt to merge the two histories.<\/p>\n
    2.4 Resolve Merge Conflicts (If Any)<\/h5>\n
    It is highly probable that you will encounter merge conflicts after using --allow-unrelated-histories<\/code>, especially if both histories have different files or different versions of the same files at their respective roots (e.g., two different README.md<\/code> files).<\/p>\n<\/blockquote>\n
    Your terminal will indicate any conflicting files:<\/p>\n
    Auto-merging README.md\nCONFLICT (add\/add): Merge conflict in README.md\nAutomatic merge failed; fix conflicts and then commit the result.\n<\/code><\/pre>\n
      \n
    1. Open the conflicting files<\/strong> in your preferred text editor (e.g., nano<\/code>, vim<\/code>, vscode<\/code>).<\/li>\n
    2. Identify and resolve conflicts<\/strong>: Git marks conflicts with <<<<<<<<\/code>, =======<\/code>, and >>>>>>><\/code>.
      <<<<<<< HEAD\nThis is the content from my local repository.\n=======\nThis is the content from the remote repository.\n>>>>>>> origin\/main\n<\/code><\/pre>\nEdit the file to include the desired content.<\/li>\n
    3. Stage the resolved files<\/strong>:
      git add . # Or git add <conflicting-file-1> <conflicting-file-2>\n<\/code><\/pre>\n<\/li>\n
    4. Commit the merge<\/strong>: Git will typically provide a default merge commit message. You can accept it or modify it.
      git commit -m "Merge remote main with --allow-unrelated-histories and resolved conflicts"\n<\/code><\/pre>\n<\/li>\n<\/ol>\n
      2.5 Push Changes to Remote (If Necessary)<\/h5>\n
      Once the merge is complete and committed locally, you can push the new, unified history to your remote repository.<\/p>\n
      git push origin main\n<\/code><\/pre>\n
      3. Alternative: Reinitialize Local Repository (Use with Caution)<\/h4>\n
      This approach discards your local repository's history and state, effectively making it a fresh clone of the remote. This is suitable if your local repository has no important uncommitted changes, or if its history is completely irrelevant compared to the remote.<\/p>\n
      3.1 Backup Local Changes (If Any)<\/h5>\n
      If you have any uncommitted or local-only committed changes that you wish to preserve, back them up.<\/p>\n
      # Stash uncommitted changes\ngit stash push -m "Pre-reinit local changes"\n\n# Or, simply copy your entire project directory\ncp -r \/path\/to\/your\/project \/path\/to\/your\/project_backup_`date +%Y%m%d%H%M%S`\n<\/code><\/pre>\n
      3.2 Remove Local .git<\/code> Directory<\/h5>\n
      Navigate into your project directory and remove the hidden .git<\/code> folder. This effectively de-initializes your local repository.<\/p>\n
      cd \/path\/to\/your\/project\nrm -rf .git\n<\/code><\/pre>\n
      3.3 Re-clone the Remote Repository<\/h5>\n
      Navigate to the parent directory of your project and clone the remote repository anew.<\/p>\n
      cd \/path\/to\/parent\/directory\ngit clone https:\/\/github.com\/your-organization\/your-repository.git your_project_name\ncd your_project_name\n<\/code><\/pre>\n
      3.4 Restore and Reapply Local Changes (If Any)<\/h5>\n
      If you stashed changes in step 3.1, you can now try to apply them. Be aware that conflicts might still occur if the remote has diverged significantly.<\/p>\n
      # If you stashed changes and are in the newly cloned repo:\ngit stash pop\n\n# Alternatively, manually copy back specific files from your backup\ncp \/path\/to\/your\/project_backup\/your_file.js .\n<\/code><\/pre>\n
      4. Alternative: Force Push (Use with EXTREME Caution)<\/h4>\n
      This option is generally NOT recommended in collaborative environments. It should only be used if you are absolutely certain that your local repository's history should completely overwrite<\/em> the remote's history, and no one else is working on that branch.<\/p>\n
      4.1 Ensure Local Repository is Exactly What You Want<\/h5>\n
      Make sure your local branch (main<\/code> in this example) contains the exact history and files you want to be on the remote.<\/p>\n
      4.2 Force Push<\/h5>\n
      # Safer variant: only forces if the remote branch hasn't been updated since your last pull\/fetch\ngit push --force-with-lease origin main\n\n# More aggressive variant: forces regardless of remote updates, can overwrite others' work\n# Use with extreme caution, only if you are absolutely sure.\n# git push --force origin main\n<\/code><\/pre>\n
      The git push --force-with-lease<\/code> or git push --force<\/code> commands will overwrite the remote branch history! All commits on the remote that are not present in your local branch will be permanently lost. This can cause significant problems for other developers working on the same branch. Only use this if you are absolutely certain of the consequences and have communicated with your team, or if you are the sole contributor and are certain the remote history is undesirable.<\/p>\n<\/blockquote>\n
      By understanding the root cause and carefully applying one of these resolution methods, particularly the --allow-unrelated-histories<\/code> flag, you can effectively overcome the "fatal: refusing to merge unrelated histories" error and continue your development workflow on Ubuntu 20.04 LTS.<\/p>\n","protected":false},"excerpt":{"rendered":"
      Fix the Git ‘refusing to merge unrelated histories’ error when pulling or merging disparate repositories on Ubuntu 20.04. Learn the root cause and resolution.<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[105],"tags":[40,106,107,6,13,108,109],"class_list":["post-39","post","type-post","status-publish","format-standard","hentry","category-git-ci-cd","tag-devops","tag-git","tag-merge","tag-troubleshooting","tag-ubuntu","tag-unrelated-histories","tag-version-control"],"_links":{"self":[{"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/posts\/39","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/comments?post=39"}],"version-history":[{"count":2,"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/posts\/39\/revisions"}],"predecessor-version":[{"id":287,"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/posts\/39\/revisions\/287"}],"wp:attachment":[{"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/media?parent=39"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/categories?post=39"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/butitworkedlocal.com\/wp-json\/wp\/v2\/tags?post=39"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}