`git submodule update --single-branch` tracks HEAD instead of branch from .gitmodules

Hello,

for a project I'm using several submodules, showing my issue with just one of them

	$ git ls-tree @:layers | grep poky
	160000 commit b33a8abe77081a2bdda0d89c61736473b2f9bb8b	poky

	$ cat .gitmodules 
	...
	[submodule "yocto_poky"]
		path = layers/poky
		url = https://git.yoctoproject.org/git/poky
		branch = scarthgap

	$ git submodule update --init --checkout --recursive --single-branch
	...
	Cloning into '/home/uwe/work/sri/poet-server/layers/poky'...
	remote: Enumerating objects: 8775, done.
	remote: Counting objects: 100% (3119/3119), done.
	remote: Compressing objects: 100% (158/158), done.
	remote: Total 8775 (delta 2974), reused 2961 (delta 2961), pack-reused 5656 (from 1)
	Receiving objects: 100% (8775/8775), 3.24 MiB | 15.45 MiB/s, done.
	Resolving deltas: 100% (6158/6158), completed with 391 local objects.
	From https://git.yoctoproject.org/git/poky
	 * branch                      b33a8abe77081a2bdda0d89c61736473b2f9bb8b -> FETCH_HEAD

so far so good. But:

	$ cd layers/poky/
	layers/poky$ git remote show origin
	* remote origin
	  Fetch URL: https://git.yoctoproject.org/git/poky
	  Push  URL: https://git.yoctoproject.org/git/poky
	  HEAD branch: master
	  Remote branch:
	    master tracked
	  Local branch configured for 'git pull':
	    master merges with remote master
	  Local ref configured for 'git push':
	    master pushes to master (up to date)

So in this submodule master is tracked, while I think it would be much more sensible to track the scarthgap branch. The further consequence is that

	$ git submodule update --remote layers/poky/
	fatal: Unable to find refs/remotes/origin/scarthgap revision in submodule path 'layers/poky'

This happens for both git version 2.47.3 (which I typically use, provided by Debian), but also on current git master (2.52.0.rc2.22.gc93f1a0fa3eb).

Best regards Uwe

On Mon, Nov 17, 2025 at 4:28 AM Uwe Kleine-König <u.kleine-koenig@baylibre.com> wrote:

Is it? You've only cloned the HEAD from the origin:

       --single-branch, --no-single-branch
           This option is only valid for the update command. Clone only one
           branch during update: HEAD or one specified by --branch.

Perhaps you want to use --branch here, and _perhaps_ update --single-branch should default to submodule.<name>.branch ?

Hello,

On Thu, Nov 20, 2025 at 11:05:00AM -0500, D. Ben Knoble wrote:

I don't. b33a8abe77081a2bdda0d89c61736473b2f9bb8b isn't included in the remote's HEAD, only in the scarthgap branch.

Well, the submodule is initialized from .gitmodules which has a specification of the branch. And the init steps works fine despite the submodule commit not being included in HEAD of the remote poky repo. I interpret that as --branch being provided (somewhat) implicitly.

And yes I'm aware I wail about something that is documented. But the documentation is silly in the same way as the code.

Yes please. `git submodule update --init` already does it right, just the fetch line in .git/modules/yocto_poky/config is wrong.

Best regards Uwe