Re: [PATCH] documentation: clarify submodule.<name>.[url, path] variables

[Stefan Beller <sbeller@google.com>]

On Mon, Oct 10, 2016 at 11:09 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Stefan Beller <sbeller@google.com> writes:
>>  submodule.<name>.path::
>> +     The path within this project for a submodule. This variable is
>> +     kept in the .gitmodules file. See linkgit:git-submodule[1] and
>> +     linkgit:gitmodules[5] for details.
>
> What does it exactly mean to be "kept"?
>
> Does it mean "never appears in .git/config, and when it appears it
> will not be used at all"?  If so we shouldn't even list it here.

I meant:
Git wont put it into .git/config on its own. If you really wanted to have
it there, you need to do it yourself.

I assumed you can overwrite the path via the config. It turns out,
the value from the config is ignored, so it doesn't even make sense
to put it into the config. Only the value from the .gitmodules file counts.

So with that knowledge, I'll just remove it here, but I'll cross check if it
is referenced else where enough.

>
> I doubt there is any reason for .path to exist in .git/config; where
> each submodule appears in the working tree is what is recorded in
> the tree object, and the "identity" (i.e. that which links a
> submodule in a tree to one of the repositories kept in
> .git/modules/*) by reverse look-up of submodule.<name>.path from
> in-tree .gitmodules, not from configuration, and it is not something
> a per-repository configuration should be able to change at the
> conceptual level.

As said above, currently we'd only rely on the .gitmodules file.

However I think this may conceptually the wrong thing to do.
The name is set in stone and ought to never be changed, unlike
the path.  But as we only obtain this information from within the
repository at all times and not make a copy of it, upstream may
go crazy and change the names within the .gitmodules file.

Then the downstream user is left with a mess and they have no
way of fixing it except by modifying the data in the repository. So it
may be a sensible thing to allow the user to create their own
path -> name mapping in the config file.

We as the Git developers may even think about whether we'd
want to have the path -> name lookup all the time from upstream,
or rather on initialization want to make a copy of the path->name
mapping. Then we can never change the name locally, but we'd
need to track upstream for rename detection of submodule.

>
>>  submodule.<name>.url::
>> -     The path within this project and URL for a submodule. These
>> -     variables are initially populated by 'git submodule init'. See
>> -     linkgit:git-submodule[1] and linkgit:gitmodules[5] for
>> -     details.
>> +     The URL for a submodule. This variable is copied from the .gitmodules
>> +     file to the git config via 'git submodule init'. The user can change
>> +     the configured URL before obtaining the submodule via 'git submodule
>> +     update'. After obtaining the submodule, this variable is kept in the
>> +     config as a boolean flag to indicate whether the submodule is of
>> +     interest to git commands.  See linkgit:git-submodule[1] and
>> +     linkgit:gitmodules[5] for details.
>
> I think it is great that you are describing that this serves two
> purposes, but "as a boolean flag" is very misleading.  It sounds as
> if at some point "git submodule $something" command stores
> true/false there.
>
>  - It overrides the URL suggested by the project in .gitmodules and
>    replace it with another URL viewed from the local environment
>    (e.g. the project may suggest you to use http://github.com/ while
>    you may have a local mirror elsewhere).
>
>  - Its presence is also used as a sign that the user is interested in
>    the submodule.

I see, that makes it clearer, I'll reword this.