threads / patch / 46812

patchDocumentation/config: clarify the meaning of submodule.<name>.update

Subject: [PATCH] Documentation/config: clarify the meaning of submodule.<name>.update

## tl;dr

12 messages between Sep 22, 2017 and Sep 26, 2017. Diffs are folded; open one to read it.

replies: 11people: 4as markdown or json

Stefan Beller· Sep 22, 2017, 21:28 UTC · lore

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/4283F0B0-BC1C-4ED1-8126-7E512D84484B@gmail.com/
Signed-off-by: Stefan Beller <sbeller@google.com>
---
 Documentation/config.txt | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)
Show changes to Documentation/config.txt +3 −4
diff --git a/Documentation/config.txt b/Documentation/config.txt
index dc4e3f58a2..b0ded777fe 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -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

-- 
2.14.0.rc0.3.g6c2e499285
Jonathan Nieder· Sep 22, 2017, 21:37 UTC · re: Stefan Beller · lore

Re: [PATCH] Documentation/config: clarify the meaning of submodule.<name>.update

Hi,
Stefan Beller wrote:
Show 5 quoted lines
> 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.

Show 5 quoted 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.
>
> [1] https://public-inbox.org/git/4283F0B0-BC1C-4ED1-8126-7E512D84484B@gmail.com/

Can you summarize what this discussion concluded with so the reader does not have to look far to understand it?

> Signed-off-by: Stefan Beller <sbeller@google.com>
Reported-by: Lars Schneider <larsxschneider@gmail.com>
Show 20 quoted lines
> ---
>  Documentation/config.txt | 7 +++----
>  1 file changed, 3 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index dc4e3f58a2..b0ded777fe 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -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].
>  
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

Stefan Beller· Sep 22, 2017, 22:52 UTC · re: Jonathan Nieder · lore

[PATCHv2] 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/4283F0B0-BC1C-4ED1-8126-7E512D84484B@gmail.com/
    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.
Reported-by: Lars Schneider <larsxschneider@gmail.com>
Signed-off-by: Stefan Beller <sbeller@google.com>
---
 Documentation/config.txt | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)
Jonathan writes:
> 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.
Show changes to Documentation/config.txt +8 −4
diff --git a/Documentation/config.txt b/Documentation/config.txt
index dc4e3f58a2..1ac0ae6adb 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -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

-- 
2.14.0.rc0.3.g6c2e499285
Jonathan Nieder· Sep 22, 2017, 22:58 UTC · re: Stefan Beller · lore

Re: [PATCHv2] Documentation/config: clarify the meaning of submodule.<name>.update

Stefan Beller wrote:
Show 7 quoted lines
> Reported-by: Lars Schneider <larsxschneider@gmail.com>
> Signed-off-by: Stefan Beller <sbeller@google.com>
> ---
>  Documentation/config.txt | 12 ++++++++----
>  1 file changed, 8 insertions(+), 4 deletions(-)
>
> Jonathan writes:
Show 17 quoted lines
>> 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.

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.

Junio C Hamano· Sep 23, 2017, 23:52 UTC · re: Jonathan Nieder · lore

Re: [PATCHv2] Documentation/config: clarify the meaning of submodule.<name>.update

Jonathan Nieder <jrnieder@gmail.com> writes:
Show 31 quoted lines
> Stefan Beller wrote:
>
>> Reported-by: Lars Schneider <larsxschneider@gmail.com>
>> Signed-off-by: Stefan Beller <sbeller@google.com>
>> ---
>>  Documentation/config.txt | 12 ++++++++----
>>  1 file changed, 8 insertions(+), 4 deletions(-)
>>
>> Jonathan writes:
>
>>> 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.
>
> 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.

Stefan Beller· Sep 25, 2017, 19:10 UTC · re: Junio C Hamano · lore

[PATCH] Documentation: consolidate submodule.<name>.update

Have one place to explain the effects of setting submodule.<name>.update instead of two.

Signed-off-by: Stefan Beller <sbeller@google.com>
---
Show 5 quoted 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(-)
Show changes to 2 files +12 −17

Documentation/config.txt, Documentation/gitmodules.txt

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 1ac0ae6adb..0d5a296b6c 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -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
diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt
index db5d47eb19..d156dee387 100644
--- a/Documentation/gitmodules.txt
+++ b/Documentation/gitmodules.txt
@@ -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.

-- 
2.14.0.rc0.3.g6c2e499285
Brandon Williams· Sep 25, 2017, 19:17 UTC · re: Stefan Beller · lore

Re: [PATCH] Documentation: consolidate submodule.<name>.update

On 09/25, Stefan Beller wrote:
Show 12 quoted lines
> Have one place to explain the effects of setting submodule.<name>.update
> instead of two.
> 
> Signed-off-by: Stefan Beller <sbeller@google.com>
> ---
> >> 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.

Show 53 quoted lines
> 
>  Documentation/config.txt     |  9 +--------
>  Documentation/gitmodules.txt | 20 +++++++++++---------
>  2 files changed, 12 insertions(+), 17 deletions(-)
> 
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index 1ac0ae6adb..0d5a296b6c 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -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
> diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt
> index db5d47eb19..d156dee387 100644
> --- a/Documentation/gitmodules.txt
> +++ b/Documentation/gitmodules.txt
> @@ -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.

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

Show 6 quoted lines
>  
>  submodule.<name>.branch::
>  	A remote branch name for tracking updates in the upstream submodule.
> -- 
> 2.14.0.rc0.3.g6c2e499285
> 
-- 
Brandon Williams
Stefan Beller· Sep 25, 2017, 22:18 UTC · re: Brandon Williams · lore

Re: [PATCH] Documentation: consolidate submodule.<name>.update

On Mon, Sep 25, 2017 at 12:17 PM, Brandon Williams <bmwill@google.com> wrote:
Show 16 quoted lines
> On 09/25, Stefan Beller wrote:
>> Have one place to explain the effects of setting submodule.<name>.update
>> instead of two.
>>
>> Signed-off-by: Stefan Beller <sbeller@google.com>
>> ---
>> >> 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.

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

Jonathan Nieder· Sep 25, 2017, 22:22 UTC · re: Stefan Beller · lore

Re: [PATCH] Documentation: consolidate submodule.<name>.update

Stefan Beller wrote:
> On Mon, Sep 25, 2017 at 12:17 PM, Brandon Williams <bmwill@google.com> wrote:
>> On 09/25, Stefan Beller wrote:
Show 30 quoted lines
>>> Have one place to explain the effects of setting submodule.<name>.update
>>> instead of two.
>>>
>>> Signed-off-by: Stefan Beller <sbeller@google.com>
>>> ---
>>>>> 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.
>
> 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.
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

Stefan Beller· Sep 25, 2017, 22:42 UTC · re: Jonathan Nieder · lore

Re: [PATCH] Documentation: consolidate submodule.<name>.update

On Mon, Sep 25, 2017 at 3:22 PM, Jonathan Nieder <jrnieder@gmail.com> wrote:
Show 36 quoted lines
> Stefan Beller wrote:
>> On Mon, Sep 25, 2017 at 12:17 PM, Brandon Williams <bmwill@google.com> wrote:
>>> On 09/25, Stefan Beller wrote:
>
>>>> Have one place to explain the effects of setting submodule.<name>.update
>>>> instead of two.
>>>>
>>>> Signed-off-by: Stefan Beller <sbeller@google.com>
>>>> ---
>>>>>> 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.
>>
>> 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.
>
> Sorry, I got lost.  Which state is as-is?
By as-is I refer to origin/pu.
> 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)

> 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.
> all wrong,
Care to spell out this bold claim?

Thanks, Stefan

Jonathan Nieder· Sep 25, 2017, 23:44 UTC · re: Stefan Beller · lore

Re: [PATCH] Documentation: consolidate submodule.<name>.update

Stefan Beller wrote:
> 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.

[...]
> On Mon, Sep 25, 2017 at 3:22 PM, Jonathan Nieder <jrnieder@gmail.com> wrote:
Show 9 quoted 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.
>
>> 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

Junio C Hamano· Sep 26, 2017, 01:30 UTC · re: Brandon Williams · lore

Re: [PATCH] Documentation: consolidate submodule.<name>.update

Brandon Williams <bmwill@google.com> writes:
Show 16 quoted lines
>> +	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.
>
> 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?

← back to recent threads