Why do submodules detach HEAD? (was Re: Incorrect and inconsistent End-Of-Line characters in .gitmodules ...)

On 18-Jul-2021, at 02:52, Rostislav Krasny [off-list ref] wrote:

[...]
I would like to take this opportunity to ask: why cloning a repository
that contains submodules sets this repository branch to its default
(master, main, whatever) but all submodules are set into a detached
HEAD mode instead of their default branches? This is actually the
reason I started to check what happens with the .gitmodules file. What
is the point in such an inconsistent behavior? There are a lot of
questions about that in Google and it seems most of the users expect
different behavior.

Submodules are cloned along with the parent repository only when
'submodule.recurse' is set to true, which I assume is the case for
your configuration.

A git clone that recurses submodules is equivalent to running
'git submodule update --init --recursive' right after the parent
project has been cloned.

The default mode for the update command is to checkout to the
revision that the parent project expects the submodule to be in, ie,
it checks out to the commit hash directly, and detaches the HEAD.

Why not checkout to a branch? This is because branches may change
which commits they point to.

For example, if you had a submodule 'foo'. I go into the 'foo'
folder and amend the last commit.

Now if I run 'submodule update' in the parent repository. If it had
checked out to the branch instead of the revision, I would be on a
different commit in 'foo' than the one that was registered by the
parent repo!

We want to have idempotence, ie, for a particular revision that is
registered by our parent project, we want 'update' to give the same
outcome every time, and not be dependent on whatever the state of the
branch is. This way we ensure that for a particular commit in the
parent project, the submodules will be in the same state for every
system in the world, after an 'update' is run.

I hope that makes sense.

(Anyone more knowledgeable than me in submodules, feel free to add
to what I am saying and correct me if I made an error!)

---
Atharva Raykar
ಅಥರ್ವ ರಾಯ್ಕರ್
अथर्व रायकर