🔀 Git: Fix a Submodule Stuck on a Detached Head After a Pull
Running git pull on a superproject updates the recorded submodule commit pointer in the index, but unless submodule.recurse is configured, it doesn’t check out that commit inside the submodule’s own working tree – and even when it does, the submodule lands at a detached HEAD pointing at that commit, not on any branch. A teammate who opens the submodule folder from that state, commits a quick fix, and later pulls again from inside it can find that commit stranded on no branch at all, invisible to git log --all and reachable only through the reflog.
🔎 The Problem
$ cd my-submodule && git status
HEAD detached at 8f21a90
$ git commit -am "quick fix"
[detached HEAD a93f102] quick fix
$ git pull
Already up to date. # pulled nothing useful; commit a93f102 is
# still only reachable from the reflog,
# not from any branch
✅ Fix: Check for a Detached Head Before You Commit Inside a Submodule
- Before making any change inside a submodule, run
git statusthere first and check for “HEAD detached at” – if you see it, create or check out a real branch before committing anything, rather than committing straight onto the detached state. - Set
submodule.recurse=trueat the superproject level so routine pull and checkout operations keep submodules in sync automatically, which reduces how often you land on a fresh detached HEAD without realizing a pull just moved it. - If a commit is already stranded, find it with
git -C <submodule> reflogand cherry-pick or branch it from there – it isn’t actually gone, just unreachable from any ref.
🚨 Why This Is Dangerous
- A commit made on a detached HEAD inside a submodule can survive for weeks only in the reflog, which has its own expiry – assuming “it’s committed, so it’s safe” skips the part where detached commits are one
git gcaway from being genuinely unrecoverable.
A submodule pull moves where HEAD points – it never promises HEAD is pointing at a branch. Check before you commit, not after.

