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

From: Atharva Raykar <raykar.ath@gmail.com>
Date: Jul 21, 2021, 07:26 UTC
Message-ID: <46F5B91F-4DBE-4F34-9395-7CC808FAC359@gmail.com>
In-Reply-To: <CANt7McHrYhSe3JsS8UKX8NgsUajwxQY4h9KTtXkEXdd0Be_+yw@mail.gmail.com>

On 18-Jul-2021, at 02:52, Rostislav Krasny <rosti.bsd@gmail.com> wrote:

Show 11 quoted lines

> 
> 
> [...]
> 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 ಅಥರ್ವ ರಾಯ್ಕರ್ अथर्व रायकर