From: Philip Oakley Date: Tue, 17 Jun 2014 22:03:14 GMT Subject: Re: [PATCH] doc git: multivar configuration parameters append to existing values Message-ID: In-Reply-To: From: "Junio C Hamano" > "Philip Oakley" 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? > Yes, that's a good start, but we still need the correction to the git(1) '-c' option text. It'll be a few days before I can get back to this. > 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..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..insteadOf`; > +you cannot use "git -c remote..url= push", > because > +you will be pushing to both the configured place and the temporary > place. > > remote..pushurl:: > The push URL of a remote repository. See linkgit:git-push[1]. > @@ -2419,6 +2426,10 @@ url..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..pushInsteadOf:: > Any URL that starts with this value will not be pushed to; > > -- Philip