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

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

[Stefan Beller]

Signed-off-by: Stefan Beller <sbeller@google.com>
---

This was raised in the discussion of 
https://public-inbox.org/git/20161006193725.31553-1-sbeller@google.com/raw

However this can go as a separate patch instead of adding it to the series.

Thanks,
Stefan

 Documentation/config.txt | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index e78293b..1f68d05 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -2812,11 +2812,18 @@ stash.showStat::
 	See description of 'show' command in linkgit:git-stash[1].
 
 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.
+
 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.
 
 submodule.<name>.update::
 	The default update procedure for a submodule. This variable
-- 
2.10.1.353.g1629400

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

[Junio C Hamano]

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 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.

>  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.

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

[Stefan Beller]

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.

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

[Junio C Hamano]

Stefan Beller <sbeller@google.com> writes:

>> 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.

Good.  I do recall we designed this part of the system in such a way
that .path is conceptually uncostimizable (it _is_ part of what the
containing tree already records), and was wondering why it is there
as if it can be overridden.

[PATCHv2] documentation: improve submodule.<name>.{url, path} description

[Stefan Beller]

Unlike the url variable a user cannot override the the path variable,
as it is part of the content together with the gitlink at the given
path. To avoid confusion do not mention the .path variable in the config
section and rely on the documentation provided in gitmodules[5].

Enhance the description of submodule.<name>.url and mention its two use
cases separately.

Signed-off-by: Stefan Beller <sbeller@google.com>
---

I think the gitmodules[5] is enough for .path, so let's just
do this one instead.

Thanks,
Stefan


 Documentation/config.txt | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index e78293b..fd775b4 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -2811,12 +2811,13 @@ stash.showStat::
 	option will show diffstat of the stash.  Defaults to true.
 	See description of 'show' command in linkgit:git-stash[1].
 
-submodule.<name>.path::
 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, the presence of this variable
+	is used as a sign whether the submodule is of interest to git commands.
+	See linkgit:git-submodule[1] and linkgit:gitmodules[5] for details.
 
 submodule.<name>.update::
 	The default update procedure for a submodule. This variable
-- 
2.10.1.382.ga23ca1b.dirty