How to fix Failed to merge submodule lib (commits don't follow merge-base) in Git

GitINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 197 views

This Git warning occurs when merging branches that have divergent submodule histories. Git cannot automatically resolve which commit the submodule should point to because both branches have made independent changes to the submodule reference.

Quick fix

Fixes Failed to merge submodule lib (commits don't follow merge-base)

git diff
  1. Identify the conflicting submodule commits
  2. Examine the submodule history
  3. Choose one side of the conflict
  4. Alternatively, merge within the submodule
git — error
git diff
Failed to merge submodule lib (commits don't follow merge-base)

What this error means

When you see "Failed to merge submodule (commits don't follow merge-base)", Git is telling you that the two branches you're trying to merge contain different submodule commit references that don't share a common ancestor in the expected merge path. In Git, a submodule is a pointer to a specific commit in another repository. When you merge two branches, Git normally finds the "merge-base" (the common ancestor commit) and applies changes from both branches. However, if both branches have updated the submodule to point to different commits that don't follow a linear path from this merge-base, Git cannot automatically determine which commit should win. This is fundamentally different from a regular file conflict because Git cannot simply show you conflicting lines of text - instead, it needs you to decide which submodule commit (or a merge of both) should be used in the resulting merge commit.

Typical symptoms

  • Git merge fails with "CONFLICT (submodule): Merge conflict in <submodule-path>"
  • Warning message: "Failed to merge submodule <name> (commits don't follow merge-base)"
  • git status shows the submodule as "both modified"
  • Merge or rebase operation halts partway through
  • git stash pop fails when stash contains submodule changes

Common causes

  1. Both branches independently updated the submodule to different commits
  2. One branch updated the submodule while another made changes within it
  3. Rebasing a branch that added or modified submodule references
  4. Stashing and unstashing changes that include submodule pointer updates
  5. Force-pushing or rewriting history in the submodule repository itself
  6. Manually removing merge conflict markers without properly resolving submodule state

How to fix "Failed to merge submodule lib (commits don't follow merge-base)"

1Identify the conflicting submodule commits

First, determine which commits each branch is pointing to in the submodule:

bash
git diff

This shows output like:

bash
diff --cc lib
index abc1234,def5678..0000000
--- a/lib
+++ b/lib

The two SHA-1 hashes (abc1234 and def5678) are the submodule commits from each branch.

2Examine the submodule history

Navigate into the submodule and check if the commits can be merged:

bash
cd lib
git log --oneline abc1234..def5678
git log --oneline def5678..abc1234

This helps you understand whether one commit is an ancestor of the other, or if they truly diverged.

3Choose one side of the conflict

If you want to keep the submodule version from the branch you're merging INTO (current branch):

bash
git checkout --ours -- lib
git add lib

Or to keep the version from the branch you're merging FROM:

bash
git checkout --theirs -- lib
git add lib

Replace "lib" with your actual submodule path.

4Alternatively, merge within the submodule

If both branches contain important changes, merge them inside the submodule:

bash
cd lib
git fetch origin
git checkout def5678  # The commit from the other branch
git merge abc1234     # Merge in the commit from current branch
# Resolve any conflicts within the submodule
git commit -m "Merge submodule changes"
cd ..
git add lib

This creates a new merge commit in the submodule that includes changes from both branches.

5Use git update-index for precise control

Git sometimes suggests using update-index to accept a specific resolution:

bash
git update-index --cacheinfo 160000 <desired-commit-hash> lib

The "160000" mode indicates a submodule (gitlink). Replace <desired-commit-hash> with the commit you want the submodule to point to.

6Complete the merge

After resolving the submodule conflict:

bash
git status  # Verify submodule shows as resolved
git commit  # Complete the merge commit

If you were doing a stash pop, remember to drop the stash manually since git stash pop doesn't auto-drop when conflicts occur:

bash
git stash drop
7For stash conflicts specifically

If this error came from git stash pop:

bash
git reset HEAD lib  # Unstage the conflicted submodule
git checkout -- lib # Reset to the current branch's version
git submodule update lib  # Update submodule to match
git stash drop  # Clean up the stash

Note: Don't include a trailing slash after the submodule name - shell tab-completion often adds one, which will cause the command to fail.

Advanced notes

### Understanding merge-base with submodules

The "merge-base" is the commit that Git identifies as the common ancestor when merging. For regular files, Git computes a three-way merge using this base. Submodules complicate this because the submodule commit reference is just a SHA-1 hash - Git cannot meaningfully merge two different hashes.

### Recursive submodule merging

Git 2.14+ supports git merge --recurse-submodules which attempts to automatically merge submodule changes:

bash
git merge --recurse-submodules=on-demand feature-branch

This will try to fast-forward submodules when possible, or create merge commits within them when both sides have changes.

### Preventing future conflicts

To minimize submodule merge conflicts:
1. Keep submodule updates in dedicated commits
2. Coordinate submodule version bumps across branches
3. Consider using git config submodule.recurse true to auto-update submodules
4. Use merge rather than rebase for branches with submodule changes when possible

### When rebasing fails

Rebasing with submodules is particularly problematic because rebase replays commits one by one. Each replayed commit that touches a submodule may conflict. In these cases, git merge is often cleaner than git rebase, even though the history looks messier.

### Submodule configuration options

Relevant git config options for submodule merging:
- submodule.recurse: Automatically recurse into submodules for many commands
- diff.submodule: Controls how submodule diffs are displayed (log, short, diff)
- status.submodulesummary: Show submodule commit summaries in git status

Frequently asked questions

What does "Failed to merge submodule lib (commits don't follow merge-base)" mean?
When you see "Failed to merge submodule (commits don't follow merge-base)", Git is telling you that the two branches you're trying to merge contain different submodule commit references that don't share a common ancestor in the expected merge path. In Git, a submodule is a pointer to a specific commit in another repository. When you merge two branches, Git normally finds the "merge-base" (the common ancestor commit) and applies changes from both branches.
How do I fix "Failed to merge submodule lib (commits don't follow merge-base)"?
This Git warning occurs when merging branches that have divergent submodule histories. Git cannot automatically resolve which commit the submodule should point to because both branches have made independent changes to the submodule reference.
What causes "Failed to merge submodule lib (commits don't follow merge-base)"?
Both branches independently updated the submodule to different commits One branch updated the submodule while another made changes within it Rebasing a branch that added or modified submodule references
Is the "Failed to merge submodule lib (commits don't follow merge-base)" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading