gitgit-submodulescheckoutgit-detached-head

git/submodule: NOT a detached ahead after update --checkout

As per documentation man git submodule update, if run with an option --checkout then it should leave submodules's HEAD in a detached state.

       --checkout
           This option is only valid for the update command. Checkout the commit recorded in the superproject on a detached HEAD in the submodule. This is the default behavior, the main use of this option is to override submodule.$name.update when set to a value other than
           checkout. If the key submodule.$name.update is either not explicitly set or set to checkout, this option is implicit.

$ pwd
/home/user/my_project

$ git branch --show-current
main

$ cat .gitmodules 
[submodule "my_submodule"]
    path = my_submodule
    url = git@git.server:user/my_submodule.git

# Note that HEAD is not detached
$ ( cd my_submodule/ && git branch --show-current )
main

$ git submodule update --init --checkout

# Now I expect a HEAD to be in a detached state but it is not. Why?
$ ( cd my_submodule/ && git branch --show-current )
main

$ git --version
git version 2.41.0

Is my interpretation of the document wrong? May someone please clarify it for me?

Solution

  • As mentioned in the comments, if the submodule is already at the commit specified in the superproject, git submodule update --init --checkout does not detach the submodule's HEAD.

    However, git submodule update --init --checkout --force does detach it.