As per documentation man git submodule update, if run with an option --rebase then it should never leave submodules's HEAD in a detached state.
--rebase
This option is only valid for the update command. Rebase the current branch onto the commit recorded in the superproject. If this option is given, the
submodule’s HEAD will not be detached. If a merge failure prevents this process, you will have to resolve these failures with git-rebase(1). If the key
submodule.$name.update is set to rebase, this option is implicit.
However it does not seem to be working as expected in a basic example below
$ pwd
/home/user/my_repo
$ cat .gitmodules
[submodule "my_submodule"]
path = my_submodule
url = git@git.server:user/my_submodule.git
branch = main
$ # This is a fresh clone, ensure that HEAD is detached
$ # This is an expected behavior so far
$ (cd my_submodule/ && git branch)
* (HEAD detached at f1129ce)
main
$ # Let's update submodules with --rebase command
$ # The expected behavior is that HEAD will not
$ # be detached, but rather pointing to main
$ git submodule update --remote --init --rebase
$ # Nope :-( HEAD is still detached
$ (cd my_submodule/ && git branch)
* (HEAD detached at f1129ce)
main
$ rpm -qf `which git`
git-core-2.39.1-1.fc37.x86_64
$ git --version
git version 2.39.1
Is my interpretation of the document wrong? May someone please clarify it for me?
Rebase the current branch onto the commit recorded in the superproject. If this option is given, the submodule’s HEAD will not be detached.
But you have not had the current branch before git submodule update --remote --init --rebase, the HEAD was already detached. So the command didn't magically move it to a branch. You should have moved it to a branch using (cd my_submodule/ && git checkout main) and then update submodules with rebase.
See https://stackoverflow.com/a/55570998/7976758 for more info. Search https://stackoverflow.com/search?q=%5Bgit-submodules%5D+rebase+detached+HEAD