Re: [PATCH] doc git: multivar configuration parameters append to existing values

[Junio C Hamano <gitster@pobox.com>]

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.  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"---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 is easy to realize that "single overrides"
   is merely a natural consequence of the appending nature of "-c".

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