Documentation/config: clarify the meaning of submodule.<name>.update
PATCH 1/1 Documentation/config: clarify the meaning of submodule.<name>.update
With more commands (that potentially change a submodule) paying attention to submodules as well as the recent discussion[1] on submodule.<name>.update, let's spell out that submodule.<name>.update is strictly to be used for configuring the "submodule update" command and not to be obeyed by other commands.
These other commands usually have a strict meaning of what they should do (i.e. checkout, reset, rebase, merge) as well as have their name overlapping with the modes possible for submodule.<name>.update.
[1] https://public-inbox.org/git/[email protected]/
--- Documentation/config.txt | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-)
Documentation/config.txt +3 -4
@@ -3085,10 +3085,9 @@ submodule.<name>.url:: See linkgit:git-submodule[1] and linkgit:gitmodules[5] for details. submodule.<name>.update:: - The default update procedure for a submodule. This variable - is populated by `git submodule init` from the - linkgit:gitmodules[5] file. See description of 'update' - command in linkgit:git-submodule[1]. + The method how a submodule is updated via 'git submodule update'. + It is populated by `git submodule init` from the linkgit:gitmodules[5] + file. See description of 'update' command in linkgit:git-submodule[1]. submodule.<name>.branch:: The remote branch name for a submodule, used by `git submodule
Signature · 1 line
2.14.0.rc0.3.g6c2e499285
Hi,
Quoted 5 lines · Stefan Beller
With more commands (that potentially change a submodule) paying attention to submodules as well as the recent discussion[1] on submodule.<name>.update, let's spell out that submodule.<name>.update is strictly to be used for configuring the "submodule update" command and not to be obeyed by other commands.
Good idea, thank you.
You'll want to update Documentation/gitmodules.txt, too.
I think this can go further: it should say explicitly that commands like "git checkout --recurse-submodules" do not pay attention to this option.
Quoted 5 lines
These other commands usually have a strict meaning of what they should do (i.e. checkout, reset, rebase, merge) as well as have their name overlapping with the modes possible for submodule.<name>.update.
Can you summarize what this discussion concluded with so the reader does not have to look far to understand it?
Quoted 1 line
Signed-off-by Stefan Beller <[email protected]>
Quoted 10 lines
--- Documentation/config.txt | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-)Documentation/config.txt +0
-0@@ -3085,10 +3085,9 @@ submodule.<name>.url:: See linkgit:git-submodule[1] and linkgit:gitmodules[5] for details.
Documentation/config.txt submodule.<name>.url:: · line 3091
Quoted 10 lines
Documentation/config.txt +3
-4submodule.<name>.update:: - The default update procedure for a submodule. This variable - is populated by `git submodule init` from the - linkgit:gitmodules[5] file. See description of 'update' - command in linkgit:git-submodule[1]. + The method how a submodule is updated via 'git submodule update'. + It is populated by `git submodule init` from the linkgit:gitmodules[5] + file. See description of 'update' command in linkgit:git-submodule[1].
Wording nits: s/The method how/The method by which/; s/via/by/
More importantly, can this be more explicit about how it is meant to be used? E.g. to say
1. This only affects "git submodule update" and doesn't affect commands like "git checkout --recurse-submodules".
2. It exists for historical reasons; settings like submodule.active and pull.rebase are more likely to be what someone is looking for.
Thanks and hope that helps,
Jonathan
PATCH v2 1/1 Documentation/config: clarify the meaning of submodule.<name>.update
With more commands (that potentially change a submodule) paying attention to submodules as well as the recent discussion[1] on submodule.<name>.update, let's spell out that submodule.<name>.update is strictly to be used for configuring the "submodule update" command and not to be obeyed by other commands.
These other commands usually have a strict meaning of what they should do (i.e. checkout, reset, rebase, merge) as well as have their name overlapping with the modes possible for submodule.<name>.update.
[1] https://public-inbox.org/git/[email protected]/
submodule.<name>.update was set to "none", triggering unexpected behavior as the submodule was thought to never be touched. However a newer version of Git taught 'git pull --rebase' to also populate and rebase submodules if they were active.
The newer options such as submodule.active and command specific flags would not have triggered unexpected behavior.
--- Documentation/config.txt | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-)
Quoted 1 line · Jonathan
You'll want to update
Documentation/gitmodules.txt, too.
No. /grumpycat
It should already be fine, as I read it as if it is only relevant to "git submodule update" there, already:
submodule.<name>.update::
Defines the default update procedure for the named submodule, i.e. how the submodule is updated by "git submodule update" command in the superproject. This is only used by git submodule init to initialize the configuration variable of the same name. Allowed values here are 'checkout', 'rebase', 'merge' or 'none'. See description of 'update' command in linkgit:git-submodule[1] for their meaning. Note that the '!command' form is intentionally ignored here for security reasons.
Documentation/config.txt +8 -4
@@ -3085,10 +3085,14 @@ submodule.<name>.url:: See linkgit:git-submodule[1] and linkgit:gitmodules[5] for details. submodule.<name>.update:: - The default update procedure for a submodule. This variable - is populated by `git submodule init` from the - linkgit:gitmodules[5] file. See description of 'update' - command in linkgit:git-submodule[1]. + The method by which a submodule is updated by 'git submodule update', + which is the only affected command, others such as + 'git checkout --recurse-submodules' are unaffected. It exists for + historical reasons, when 'git submodule' was the only command to + interact with submodules; settings like `submodule.active` + and `pull.rebase` are more specific. It is populated by + `git submodule init` from the linkgit:gitmodules[5] file. + See description of 'update' command in linkgit:git-submodule[1]. submodule.<name>.branch:: The remote branch name for a submodule, used by `git submodule
Signature · 1 line
2.14.0.rc0.3.g6c2e499285
Quoted 15 lines · Stefan Beller
Reported-by Lars Schneider <[email protected]>Signed-off-by Stefan Beller <[email protected]>--- Documentation/config.txt | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-)Quoted 1 line · Jonathan
You'll want to update
Documentation/gitmodules.txt, too.No. /grumpycat
It should already be fine, as I read it as if it is only relevant to "git submodule update" there, already:
Quoted 10 lines
submodule.<name>.update::
Defines the default update procedure for the named submodule, i.e. how the submodule is updated by "git submodule update" command in the superproject. This is only used bygit submodule initto initialize the configuration variable of the same name. Allowed values here are 'checkout', 'rebase', 'merge' or 'none'. See description of 'update' command in linkgit:git-submodule[1] for their meaning. Note that the '!command' form is intentionally ignored here for security reasons.
I disagree. Actually, I think the git-config(1) blurb could just point here, and that the text here ought to be clear about what commands it affects and how an end user would use it.
Quoted 28 lines · Jonathan Nieder
Quoted 15 lines · Stefan Beller
Reported-by Lars Schneider <[email protected]>Signed-off-by Stefan Beller <[email protected]>--- Documentation/config.txt | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-)Quoted 1 line · Jonathan
You'll want to update
Documentation/gitmodules.txt, too.No. /grumpycat
It should already be fine, as I read it as if it is only relevant to "git submodule update" there, already:
Quoted 10 lines
submodule.<name>.update::
Defines the default update procedure for the named submodule, i.e. how the submodule is updated by "git submodule update" command in the superproject. This is only used bygit submodule initto initialize the configuration variable of the same name. Allowed values here are 'checkout', 'rebase', 'merge' or 'none'. See description of 'update' command in linkgit:git-submodule[1] for their meaning. Note that the '!command' form is intentionally ignored here for security reasons.
Quoted 3 lines
I disagree. Actually, I think the git-config(1) blurb could just point here, and that the text here ought to be clear about what commands it affects and how an end user would use it.
I tend to agree with the consolidation. It's not like this patch makes things worse, but as we've already diverted our attention to this area and took time to review, if it is a simple update we can make before we apply, that is better than having to remember and come back to patch the result of this step further.
In any case, thanks for reporting, attempting to improve and reviewing, all.
PATCH 1/1 Documentation: consolidate submodule.<name>.update
Have one place to explain the effects of setting submodule.<name>.update instead of two.
---
Quoted 5 lines
Quoted 3 lines
I disagree. Actually, I think the git-config(1) blurb could just point here, and that the text here ought to be clear about what commands it affects and how an end user would use it.
I tend to agree with the consolidation.
Something like this?
Documentation/config.txt | 9 +-------- Documentation/gitmodules.txt | 20 +++++++++++--------- 2 files changed, 12 insertions(+), 17 deletions(-)
Documentation/config.txt +1 -8
@@ -3085,14 +3085,7 @@ submodule.<name>.url:: See linkgit:git-submodule[1] and linkgit:gitmodules[5] for details. submodule.<name>.update:: - The method by which a submodule is updated by 'git submodule update', - which is the only affected command, others such as - 'git checkout --recurse-submodules' are unaffected. It exists for - historical reasons, when 'git submodule' was the only command to - interact with submodules; settings like `submodule.active` - and `pull.rebase` are more specific. It is populated by - `git submodule init` from the linkgit:gitmodules[5] file. - See description of 'update' command in linkgit:git-submodule[1]. + See `submodule.<name>.update` in linkgit:gitmodules[5]. submodule.<name>.branch:: The remote branch name for a submodule, used by `git submodule
Documentation/gitmodules.txt +11 -9
@@ -38,15 +38,17 @@ submodule.<name>.url:: In addition, there are a number of optional keys: submodule.<name>.update:: - Defines the default update procedure for the named submodule, - i.e. how the submodule is updated by "git submodule update" - command in the superproject. This is only used by `git - submodule init` to initialize the configuration variable of - the same name. Allowed values here are 'checkout', 'rebase', - 'merge' or 'none'. See description of 'update' command in - linkgit:git-submodule[1] for their meaning. Note that the - '!command' form is intentionally ignored here for security - reasons. + The method by which a submodule is updated by 'git submodule update', + which is the only affected command, others such as + 'git checkout --recurse-submodules' are unaffected. It exists for + historical reasons, when 'git submodule' was the only command to + interact with submodules; settings like `submodule.active` + and `pull.rebase` are more specific. It is copied to the config + by `git submodule init` from the .gitmodules file. + Allowed values here are 'checkout', 'rebase', 'merge' or 'none'. + See description of 'update' command in linkgit:git-submodule[1] + for their meaning. Note that the '!command' form is intentionally + ignored here for security reasons. submodule.<name>.branch:: A remote branch name for tracking updates in the upstream submodule.
Signature · 1 line
2.14.0.rc0.3.g6c2e499285
Re: [PATCH] Documentation: consolidate submodule.<name>.update
Quoted 4 lines · Stefan Beller
Have one place to explain the effects of setting submodule.<name>.update instead of two.
Signed-off-by Stefan Beller <[email protected]>
Quoted 8 lines
---
Quoted 5 lines
Quoted 3 lines
I disagree. Actually, I think the git-config(1) blurb could just point here, and that the text here ought to be clear about what commands it affects and how an end user would use it.
I tend to agree with the consolidation.
Something like this?
I like the consolidation, its easier to keep up to date when its only in one place.
Quoted 43 lines
Documentation/config.txt | 9 +-------- Documentation/gitmodules.txt | 20 +++++++++++--------- 2 files changed, 12 insertions(+), 17 deletions(-)Documentation/config.txt +1
-8@@ -3085,14 +3085,7 @@ submodule.<name>.url:: See linkgit:git-submodule[1] and linkgit:gitmodules[5] for details. submodule.<name>.update:: - The method by which a submodule is updated by 'git submodule update', - which is the only affected command, others such as - 'git checkout --recurse-submodules' are unaffected. It exists for - historical reasons, when 'git submodule' was the only command to - interact with submodules; settings like `submodule.active` - and `pull.rebase` are more specific. It is populated by - `git submodule init` from the linkgit:gitmodules[5] file. - See description of 'update' command in linkgit:git-submodule[1]. + See `submodule.<name>.update` in linkgit:gitmodules[5]. submodule.<name>.branch:: The remote branch name for a submodule, used by `git submoduleDocumentation/gitmodules.txt +1
-9@@ -38,15 +38,17 @@ submodule.<name>.url:: In addition, there are a number of optional keys: submodule.<name>.update:: - Defines the default update procedure for the named submodule, - i.e. how the submodule is updated by "git submodule update" - command in the superproject. This is only used by `git - submodule init` to initialize the configuration variable of - the same name. Allowed values here are 'checkout', 'rebase', - 'merge' or 'none'. See description of 'update' command in - linkgit:git-submodule[1] for their meaning. Note that the - '!command' form is intentionally ignored here for security - reasons. + The method by which a submodule is updated by 'git submodule update',
Documentation/gitmodules.txt submodule.<name>.url:: · line 51
Quoted 10 lines
Documentation/gitmodules.txt +10
-0+ which is the only affected command, others such as + 'git checkout --recurse-submodules' are unaffected. It exists for + historical reasons, when 'git submodule' was the only command to + interact with submodules; settings like `submodule.active` + and `pull.rebase` are more specific. It is copied to the config + by `git submodule init` from the .gitmodules file. + Allowed values here are 'checkout', 'rebase', 'merge' or 'none'. + See description of 'update' command in linkgit:git-submodule[1] + for their meaning. Note that the '!command' form is intentionally + ignored here for security reasons.
This probably needs to be tweaked a bit to say that the '!command' form is ignored by submodule init, in that it isn't copied over from the .gitmodules file, but if it is configured in your config it will be respected by 'submodule update'.
Quoted 6 lines
Documentation/gitmodules.txt +0
-0submodule.<name>.branch:: A remote branch name for tracking updates in the upstream submodule.Signature · 1 line
2.14.0.rc0.3.g6c2e499285
Signature · 1 line
Brandon Williams
Re: [PATCH] Documentation: consolidate submodule.<name>.update
Quoted 10 lines · Brandon Williams
Quoted 9 lines · Stefan Beller
Have one place to explain the effects of setting submodule.<name>.update instead of two.
Signed-off-by Stefan Beller <[email protected]>---
Quoted 4 lines
Quoted 3 lines
I disagree. Actually, I think the git-config(1) blurb could just point here, and that the text here ought to be clear about what commands it affects and how an end user would use it.
Quoted 6 lines
Quoted 3 lines
Quoted 1 line
I tend to agree with the consolidation.
Something like this?
I like the consolidation, its easier to keep up to date when its only in one place.
After thinking about it further, I'd like to withdraw this patch for now.
The reason is that this would also forward point to git-submodule.txt, such that we'd still have 2 places
in which it is explained. The current situation with explaining it in 3 places is not too bad as each place hints at their specific circumstance:
git-submodule.txt explains the values to set itself. gitmodules.txt explains what the possible fields in that file are,
and regarding this field it points out it is ignored in the init call.
config.txt: actually describe the effects of the setting.
I think we can keep it as-is for now.
Thanks,
Stefan
Re: [PATCH] Documentation: consolidate submodule.<name>.update
Quoted 32 lines · Stefan Beller
Quoted 11 lines · Brandon Williams
Quoted 9 lines · Stefan Beller
Have one place to explain the effects of setting submodule.<name>.update instead of two.
Signed-off-by Stefan Beller <[email protected]>---
Quoted 4 lines
Quoted 3 lines
I disagree. Actually, I think the git-config(1) blurb could just point here, and that the text here ought to be clear about what commands it affects and how an end user would use it.
Quoted 6 lines
Quoted 3 lines
Quoted 1 line
I tend to agree with the consolidation.
Something like this?
I like the consolidation, its easier to keep up to date when its only in one place.
After thinking about it further, I'd like to withdraw this patch for now.
The reason is that this would also forward point to git-submodule.txt, such that we'd still have 2 places
in which it is explained. The current situation with explaining it in 3 places is not too bad as each place hints at their specific circumstance:
git-submodule.txt explains the values to set itself. gitmodules.txt explains what the possible fields in that file are,
and regarding this field it points out it is ignored in the init call.
config.txt: actually describe the effects of the setting.
Quoted 1 line
I think we can keep it as-is for now.
Sorry, I got lost. Which state is as-is?
As a user, how do I find out what submodule.*.update is going to do and which commands will respect it?
Maybe we should work on first wordsmithing the doc and then figuring out where it goes? The current state of the doc with (?) three different texts, all wrong, doesn't seem like a good state to preserve.
Thanks,
Jonathan
Re: [PATCH] Documentation: consolidate submodule.<name>.update
Quoted 33 lines · Jonathan Nieder
Quoted 32 lines · Stefan Beller
Quoted 11 lines · Brandon Williams
Quoted 9 lines · Stefan Beller
Have one place to explain the effects of setting submodule.<name>.update instead of two.
Signed-off-by Stefan Beller <[email protected]>---
Quoted 4 lines
Quoted 3 lines
I disagree. Actually, I think the git-config(1) blurb could just point here, and that the text here ought to be clear about what commands it affects and how an end user would use it.
Quoted 6 lines
Quoted 3 lines
Quoted 1 line
I tend to agree with the consolidation.
Something like this?
I like the consolidation, its easier to keep up to date when its only in one place.
After thinking about it further, I'd like to withdraw this patch for now.
The reason is that this would also forward point to git-submodule.txt, such that we'd still have 2 places
in which it is explained. The current situation with explaining it in 3 places is not too bad as each place hints at their specific circumstance:
git-submodule.txt explains the values to set itself. gitmodules.txt explains what the possible fields in that file are,
and regarding this field it points out it is ignored in the init call.
config.txt: actually describe the effects of the setting.
Quoted 3 lines
Quoted 1 line
I think we can keep it as-is for now.
Sorry, I got lost. Which state is as-is?
By as-is I refer to origin/pu.
Quoted 2 lines
As a user, how do I find out what submodule.*.update is going to do and which commands will respect it?
The user would discover it via 'man git-config' I would assume, which covers any config variable? It also directs to git-submodule which is more detailed, but the text there is suitable for the casual reader. (pu has origin/sb/doc-config-submodule-update)
Quoted 3 lines
Maybe we should work on first wordsmithing the doc and then figuring out where it goes? The current state of the doc with (?) three different texts,
such that each different text highlights each locations purpose.
Quoted 1 line
all wrong,
Care to spell out this bold claim?
Thanks,
Stefan
Re: [PATCH] Documentation: consolidate submodule.<name>.update
Quoted 1 line · Stefan Beller
By as-is I refer to origin/pu.
Ah, okay. I'm not in that habit because pu frequently loses topics --- it's mostly useful as a tool to (1) distribute topic branches and
(2) check whether they are compatible with each other.
[...]
Quoted 11 lines · Jonathan Nieder
Quoted 4 lines
Maybe we should work on first wordsmithing the doc and then figuring out where it goes? The current state of the doc with (?) three different texts,
such that each different text highlights each locations purpose.
Quoted 1 line
all wrong,
Care to spell out this bold claim?
In the state of "master", "man git-config" tells me that
[submodule "<name>"] update = ...
sets the "default update procedure for a submodule". It suggests that I read about "git submodule update" in git-submodule(1) for more details. This is problematic because
1. It doesn't tell me when I should and should not set it.
2. I would expect "git checkout --recurse-submodules" to respect the default update procedure.
3. It doesn't tell me what commands like "git fetch --recurse-submodules" will do.
4. It doesn't point me to better alternatives, when this configuration doesn't fit my use case.
"man git-submodule" doesn't have a section on submodule.<name>.update. It has references scattered throughout the manpage. It only tells me how the setting affects the "git submodule update" command and doesn't address the problems (1)-(4).
"man gitmodules" also refers to this setting as the "default update procedure for the named submodule". It doesn't answer the questions (1)-(4) either.
Thanks and hope that helps,
Jonathan
Re: [PATCH] Documentation: consolidate submodule.<name>.update
In reply to Brandon WilliamsQuoted 8 lines · Brandon Williams
Quoted 8 lines
Documentation/gitmodules.txt +8
-0+ The method by which a submodule is updated by 'git submodule update', + which is the only affected command, others such as + 'git checkout --recurse-submodules' are unaffected. It exists for + historical reasons, when 'git submodule' was the only command to + interact with submodules; settings like `submodule.active` + and `pull.rebase` are more specific. It is copied to the config + by `git submodule init` from the .gitmodules file. + Allowed values here are 'checkout', 'rebase', 'merge' or 'none'.
Quoted 8 lines
Documentation/gitmodules.txt submodule.<name>.url:: · line 51
Quoted 3 lines
Documentation/gitmodules.txt +3
-0+ See description of 'update' command in linkgit:git-submodule[1] + for their meaning. Note that the '!command' form is intentionally + ignored here for security reasons.This probably needs to be tweaked a bit to say that the '!command' form is ignored by submodule init, in that it isn't copied over from the .gitmodules file, but if it is configured in your config it will be respected by 'submodule update'.
I do not think gitmodules.txt is the place to say anything more than what Stefan's patch says above. Perhaps config.txt should mention that in addition to what the variable with the same in .gitmodules can take, it is allowed to use the !command form.
IOW, in config.txt
submodule.<name>.update::
Specifies how 'git submodule update' should work on the named submodule. In addition to the values that can be specified in (and copied from) .gitmodules (see linkgit:gitmodules[5]), !command form can also be used.
or something, perhaps?