Git submodule is in “detached head” state after cloning and submodule update

A submodule is always checked out as a detached HEAD (see “Why did git detach my head?“), since the index of the parent repo contains only the SHA1 as a special entry in its index, as explained by Gary Fixler‘s answer.

Even if you configure your submodule to follow a branch (or convert an existing submodule to follow a branch), a git submodule update --remote would checkout the latest SHA1 of that remote branch, but the result would by default be a detached HEAD.
Only by adding --merge or --rebase to that command (git submodule update --remote (--merge/--rebase)) would you get a non-detached HEAD, as seen in Simba‘s answer): by default, the master branch.

If you don’t update that way (git submodule update --remote (--merge/--rebase)), then you need to go in that submodule and make a branch yourself there.

If you want to contribute to said submodule (making new commits in it), it is a good idea to create a new branch.

cd mySubmodule
git checkout -b aNewBranch
# work
git add .
git commit -m "new commits"
git push -u origin aNewBranch

# record the new submodule state in the parent repo:
cd ..
git add mySubmodule
git commit -m "new state of mySubmodule"
git push

---

Note for Git 2.16 (Q1 2018): “git checkout --recursive” may overwrite and rewind the history of the branch that happens to be checked out in submodule
repositories, which might not be desirable.
Detach the HEAD but still allow the recursive checkout to succeed in such a case.

See commit 57f22bf (28 Jul 2017), and commit 3ef2538 (24 Jul 2017) by Stefan Beller (stefanbeller).
^{(Merged by Junio C Hamano — gitster — in commit 0b75572, 06 Dec 2017)}

recursive submodules: detach HEAD from new state

When a submodule is on a branch and in its superproject you run a
recursive checkout, the branch of the submodule is updated to what the
superproject checks out.
This is very unexpected in the current model of Git as e.g. ‘submodule update‘ always detaches the submodule HEAD.

Despite having plans to have submodule HEADS not detached in the future,
the current behavior is really bad as it doesn’t match user expectations
and it is not checking for loss of commits (only to be recovered via the
reflog).

Detach the HEAD unconditionally in the submodule when updating it.