documentation: clarify submodule.<name>.[url, path] variables
PATCH 1/1 documentation: clarify submodule.<name>.[url, path] variables
---
This was raised in the discussion of
https://public-inbox.org/git/[email protected]/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(-)
Documentation/config.txt +11 -4
@@ -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
Signature · 1 line
2.10.1.353.g1629400
Documentation/config.txt stash.showStat:: · line 2817
Quoted 4 lines · Stefan Beller
submodule.<name>.path::
Documentation/config.txt +3
-0+ 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.
Documentation/config.txt stash.showStat:: · line 2826
Quoted 12 lines
submodule.<name>.url::
Documentation/config.txt +7
-4- 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.
Quoted 10 lines · Junio C Hamano
Documentation/config.txt stash.showStat:: · line 2817
Quoted 4 lines · Stefan Beller
submodule.<name>.path::
Documentation/config.txt +3
-0+ 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.
Quoted 9 lines
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.
Quoted 19 lines
Documentation/config.txt stash.showStat:: · line 2826
Quoted 13 lines
submodule.<name>.url::
Documentation/config.txt +7
-4- 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.
Quoted 7 lines
- 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.
Quoted 7 lines · Stefan Beller
Quoted 2 lines
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.
Quoted 6 lines
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.
PATCH v2 1/1 documentation: improve submodule.<name>.{url, path} description
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.
---
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(-)
Documentation/config.txt +6 -5
@@ -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
Signature · 1 line
2.10.1.382.ga23ca1b.dirty