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

> "Philip Oakley" <philipoakley@iee.org> writes:
>
>>>                                                                   ---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).
>
> I think that is what I was driving at.  If we do not tell the reader
> that, perhaps we should and everything else will fall as natural
> consequence of that understanding.
>
>>> * 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.
>
> I think those who tried "-c remote.*.url" would be helped better by
> having a see-also in the documentation on "remote.*.url" that refers
> them to "insteadOf" noting that "remote.*.url" is a multi-value
> variable and appending different definition will not make "the last
> one wins".  After all "-c" is merely *one* way to append.
>
> The next person who gets confused may say "I added remote.origin.url
> at the end of my $repo/.git/config expecting that the value to be
> used"; the answer would be the same "the variable is multi-valued;
> adding a new value is not the right way to futz with it.  You either
> need to replace, or if you do not want to replace, use insteadOf".
>
> That is the second reason why the mention of insteadOf does not
> belong to the description of "-c var=value".
>
> Perhaps something like this as a starting point?
>

> Documentation/config.txt | 11 +++++++++++
> 1 file changed, 11 insertions(+)
>
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index 1d718bd..357cc02 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -2108,6 +2108,13 @@ remote.pushdefault::
> remote.<name>.url::
>  The URL of a remote repository.  See linkgit:git-fetch[1] or
>  linkgit:git-push[1].
> ++
> +Note that this variable is multi-valued (e.g. "git push there" with
> +multiple `remote.there.url` will push to all the named repositories),
> +and does not follow the "last-one-survives" rule.  When you want to
> +temporarily redirect a push to somewhere else, see
> `url.<base>.insteadOf`;
> +you cannot use "git -c remote.<name>.url=<temporary URL> push",
> because
> +you will be pushing to both the configured place and the temporary
> place.
>
> remote.<name>.pushurl::
>  The push URL of a remote repository.  See linkgit:git-push[1].
> @@ -2419,6 +2426,10 @@ url.<base>.insteadOf::
>  the best alternative for the particular user, even for a
>  never-before-seen repository on the site.  When more than one
>  insteadOf strings match a given URL, the longest match is used.
> ++
> +When you want to redirect a push to `$URL` (e.g. `site.xz:myrepo`)
> +temporarily to somewhere else (e.g. `othersite.xz:myrepo`), you can
> +use "git -c url.othersite.xz:myrepo.insteadOf=site.xz:myrepo push
> ..."
>
> url.<base>.pushInsteadOf::
>  Any URL that starts with this value will not be pushed to;
>
>