Re: [PATCH] Re: Bug with "git submodule update" + subrepo with differing path/name?

[Stefan Beller <sbeller@google.com>]

On Thu, Dec 21, 2017 at 8:21 AM, Andreas Urke <arurke@gmail.com> wrote:
> If I am entering into undefined behavior territory with the renaming
> then there might not be any point to pursue this further, but in any
> case, script below:
>
> Apologies up-front for the verbosity, there are probably a lot of
> unnecessary steps and git shortcuts missed - I just wanted it to
> exactly match my scenario. Note that it is divided into two parts as
> it requires you to edit .gitmodules.
>
> Part 1:
>
> cd ~/
> # Make sub repos and add a commit to each
> mkdir super && cd super
> mkdir sub1 && mkdir sub2
> cd sub1
> git init && touch first && git add . && git commit -m "first"
> cd ../sub2
> git init && touch first && git add . && git commit -m "first"
> cd ..
>
> # Make super repo, add subrepos, and commit
> git init
> git submodule add ./sub1
> git submodule add ./sub2
> git add .
> git commit -m "first"
>
> # Edit .gitmodules, change sub2 name and path to sub2_newname:
> # $ cat .gitmodules
> # [submodule "sub1"]
> # path = sub1
> # url = ./sub1
> # [submodule "sub2_newname"]
> # path = sub2
> # url = ./sub2_newname
>

A couple of things here:
(a) In a script you could do this via
    git config -f .gitmodules --rename-section <old> <new>
(b) This is not just undefined, but rather Git explicitly assumes
    the user does not rename the section themselves.

The reason for this is found in gits history:
1. submodules were invented
2. submodule configuration such as where to obtain
    the submodule from needs some place, and at the time
    submodule.<path>.url inside the .gitmodules file seemed
    like a good idea.
3. "What if we want git-mv, git-rm support for submodules?"
    Or for example when bisecting and jumping between revisions
    where the submodule exists or does not exists. To solve
    this problem, the concept of a "submodule name" was invented,
    such that the submodules git dir can be put into the
    superprojects .git/modules/<name> dir, and the working tree
    only needs to have a ".git" file pointing at that gitdir. The the
    working tree of the submodule can be removed while keeping
    the submodules git dir (with potentially important information
    such as local-only commits) around! Success!

    The transition path is also easy:
    These newly "named" submodules have an additional entry of
    'submodule.<name>.path =<path>'. Note how the subsection
    part of the config changed its meaning, but that is ok, as the
    name is allowed to be equal to the <path> value, and keeps
    all config related to one submodule in one section. Easy but
    confusing as now we have to adhere to a couple assumptions:
    The <path> value must match where it is in the working tree,
    the <name> however must not be changed because that is
    where we'll find its repository inside the superproject.
    And confusingly these two keys have often the same value,
    for this historic reason.

4. (rather lately): We need to fix the submodule mess.
    While in (3) we were unclear about name/path issues,
    and tried to be super backwards compatible, now we'd
    rather want the submodules to be well-defined. So we'll
    try to write some docs, such as gitsubmodules [1] in addition
    to the usage manual of "git submodule"[2]. Of course there is
    still the description of the .gitmodules file[3].

[1] https://www.kernel.org/pub/software/scm/git/docs/gitsubmodules.html
[2] https://www.kernel.org/pub/software/scm/git/docs/git-submodule.html
[3] https://www.kernel.org/pub/software/scm/git/docs/gitmodules.html

I guess in [1] we'd want to add a discussion on what the <name> and
what the <path> is for and why one can change but not the other.

I think you ran into trouble here because you and Git had
differing assumptions on some part of the submodule model.
Is there any part of the documentation, configuration or some
commands that would have helped explaining some of these things?
(i.e. What do we best patch to help others from running into the
same issue?)

Thanks,
Stefan