submodules: use default branch of the remote when a submodule's branch is not explicitly defined in .gitmodules

[jgoosens]

This issue expands on #1058

My current setup is the following: a superrepo, whose default branch is main, and 4 submodules, 2 of which have default branch main (just like the superrepo), and 2 of which have master as their default branch.

My .gitmodules file looks like this:

[submodule "submodule-a"]
    path = submodule-a
    url = <remote URI>
[submodule "submodule-b"]
    path = submodule-b
    url = <remote URI>
[submodule "submodule-c"]
    path = submodule-c
    url = <remote URI>
    branch = master
[submodule "submodule-d"]
    path = submodule-d
    url = <remote URI>
    branch = master

When I clone without initializing the submodules, and subsequently run

repo.submodule_update(recursive=True, init=True, force_reset=True)

I get the equivalent behaviour of git submodule update --init --recursive, but it still prints the Failed to checkout tracking branch refs/heads/master warning. So far, so good.

Now, in theory, running

repo.submodule_update(recursive=True, init=True)

should behave equivalently to git submodule update --init --recursive --remote, but it ends up in a state like described in #1058.

---

As I commented on the issue above, I could get around this issue by "correctly" initializing my .gitmodules file first by running

git submodule set-branch -b main submodule-a
git submodule set-branch -b main submodule-b

For issue #1058, this is still a valid comment (hence my posting it there), as it's unlikely that the default branch is develop and it's likely that the superrepo branch differs from the submodule's.

Note, however, that in my use-case the superrepo's and the "incorrectly configured" submodules' branches match (main, which is very common), yet it still spits out the warning above at best and leaves you in an inconsistent state at worst.

Proposed enhancement: If the submodule config does not provide a branch explicitly, the ref to check out should be the default branch of the submodule remote, or, if that is unknown information, the default branch of the superrepo. Thus, there's a priority of refs to try out:

• branch mentioned explicitly in .gitmodules entry
• default branch of remote
• default branch of superrepo's remote
• current behaviour as last resort fallback

[Byron]

Thanks for reporting!

The submodules implementation here is very problematic as it's non-standard, trying to be 'smarter' while ending up working correctly only in a small set of cases.

Any improvements are welcome if they are accompanied by a test, even though the whole implementation is probably inherently broken beyond repair. Maybe I am also too dismissive towards my work of the past.