Re: [PATCH] doc git: multivar configuration parameters append to existing values
From: "Junio C Hamano" <gitster@pobox.com>
Show 40 quoted lines
> Philip Oakley <philipoakley@iee.org> writes:
>
>> When the '-c' option is used to pass alternate URLs or similar
>> multivar parameters to git commands the effect is not what the user
>> expected [1,2].
>>
>> Clarify that multivar configuration parameters do not supercede
>> previous values. Suggest an alternative style parameter.
>>
>> [1] http://article.gmane.org/gmane.comp.version-control.git/250427
>> [2] http://article.gmane.org/gmane.comp.version-control.git/251529
>>
>> Signed-off-by: Philip Oakley <philipoakley@iee.org>
>> ---
>> Documentation/git.txt | 5 ++++-
>> 1 file changed, 4 insertions(+), 1 deletion(-)
>>
>> diff --git a/Documentation/git.txt b/Documentation/git.txt
>> index 3bd68b0..bedbd76 100644
>> --- a/Documentation/git.txt
>> +++ b/Documentation/git.txt
>> @@ -440,7 +440,10 @@ example the following invocations are
>> equivalent:
>>
>> -c <name>=<value>::
>> Pass a configuration parameter to the command. The value
>> - given will override values from configuration files.
>> + given will override single valued variables from configuration
>> + files, and append to multivar variables. Previous multivar values
>> + remain in effect. Use "insteadOf" style config variables when an
>> + over-ride is needed.
>> The <name> is expected in the same format as listed by
>> 'git config' (subkeys separated by dots).
>
> I have two doubts, while appreciating the overall direction to
> clarify things very much.
>
> * "single overrides, multiple appends" is not a wrong explanation
> per-se, but sounds like an arbitrary rule that forces people to
> memorize.
At the time it felt like the most compact method of informing the reader.
> I wonder if it makes it less burdensome for readers
> if
> we just said "Git acts as if the given configuration is specified
> at the very end of the configuration files"
I'd started with something like that..
Show 5 quoted lines
> ---once
> the reader
> understands that Git reads all configuration varilables of the
> same name and the code paths that *use* one of them pick the one
> defined the last,
It's this step that's a concern. We shouldn't be forcing the reader to implicitly grok that, especially as we don't actually say it elsewhere (in the regular documentation).
> it is easy to realize that "single
> overrides"
> is merely a natural consequence of the appending nature of "-c".
Perhaps I should just say that [say it that way].
Show 5 quoted lines
>
> * The last sentence added, i.e. "insteadof"-style, will not be
> understood by any reader other than those who tried to use "-c"
> on remote.*.url variables and does not belong here. A better
> way/place to give that information is needed.
I just wanted to indicate that some multivars do have get-out [override] config parameters, though we aren't consistent about their names yet, while giving a clue as to a typical name style.
It would also be good to get feedback from Robert and Ævar on whether the text would actually be informative to them, as they took the time to report the original 'conceptual breakage'.
Philip
Philip Oakley
