Re: [PATCH] submodule: Fix documentation of update subcommand

[Jens Lehmann <Jens.Lehmann@web.de>]

Am 03.11.2014 um 20:02 schrieb Junio C Hamano:
> Michal Sojka <sojkam1@fel.cvut.cz> writes:
>
>> The documentation says that submodule.$name.update can be overridden by
>> --checkout only if its value is `none`. This is not true, because both
>> implementation and documentation of --checkout specifies that the
>> override applies to all possible values.
>>
>> Signed-off-by: Michal Sojka <sojkam1@fel.cvut.cz>
>> ---
>>   Documentation/git-submodule.txt | 2 +-
>>   1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
>> index 8e6af65..84ab577 100644
>> --- a/Documentation/git-submodule.txt
>> +++ b/Documentation/git-submodule.txt
>> @@ -158,7 +158,7 @@ update::
>>   	checkout the commit specified in the index of the containing repository.
>>   	This will make the submodules HEAD be detached unless `--rebase` or
>>   	`--merge` is specified or the key `submodule.$name.update` is set to
>> -	`rebase`, `merge` or `none`. `none` can be overridden by specifying
>> +	`rebase`, `merge` or `none`. This can be overridden by specifying
>>   	`--checkout`. Setting the key `submodule.$name.update` to `!command`
>>   	will cause `command` to be run. `command` can be any arbitrary shell
>>   	command that takes a single argument, namely the sha1 to update to.
>
> Thanks.  This looks sensible, judging only from the text (iow I
> didn't check if there were legitimate reason why rebase/merge
> settings should not be overriden from the command line).

This was introduced in e6a1c43aaf (document submdule.$name.update=none
option for gitmodules), and I agree with Michal that we should fix it.
But I think we should rather say "This can be overridden by specifying
'--merge', '--rebase' or `--checkout`." here, as the other two options
also override the update setting. So I think we should queue this:

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 8e6af65..84ab577 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -158,7 +158,7 @@ update::
  	checkout the commit specified in the index of the containing repository.
  	This will make the submodules HEAD be detached unless `--rebase` or
  	`--merge` is specified or the key `submodule.$name.update` is set to
-	`rebase`, `merge` or `none`. `none` can be overridden by specifying
+	`rebase`, `merge` or `none`. This can be overridden by using '--merge',
+	'--rebase' or
  	`--checkout`. Setting the key `submodule.$name.update` to `!command`
  	will cause `command` to be run. `command` can be any arbitrary shell
  	command that takes a single argument, namely the sha1 to update to.

Apart from that I'm all for it.