{"thread":{"id":"36924","subject":"[PATCH] doc git: multivar configuration parameters append to existing values","startedAt":"2014-06-16T12:49:12Z","lastAt":"2014-06-17T22:03:14Z","messageCount":8,"participants":["Philip Oakley","Tanay Abhra","Junio C Hamano","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"244247","messageId":"1402922952-172-1-git-send-email-philipoakley@iee.org","threadId":"36924","inReplyTo":null,"subject":"[PATCH] doc git: multivar configuration parameters append to existing values","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-06-16T12:49:12Z","receivedAt":"2014-06-16T12:49:12Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"When the '-c' option is used to pass alternate URLs or similar\nmultivar parameters to git commands the effect is not what the user\nexpected [1,2].\n\nClarify that multivar configuration parameters do not supercede\nprevious values. Suggest an alternative style parameter.\n\n[1] http://article.gmane.org/gmane.comp.version-control.git/250427\n[2] http://article.gmane.org/gmane.comp.version-control.git/251529\n\nSigned-off-by: Philip Oakley \n---\n Documentation/git.txt | 5 ++++-\n 1 file changed, 4 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 3bd68b0..bedbd76 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -440,7 +440,10 @@ example the following invocations are equivalent:\n \n -c =::\n \tPass a configuration parameter to the command. The value\n-\tgiven will override values from configuration files.\n+\tgiven will override single valued variables from configuration\n+\tfiles, and append to multivar variables. Previous multivar values\n+\tremain in effect. Use \"insteadOf\" style config variables when an\n+\tover-ride is needed.\n \tThe is expected in the same format as listed by\n \t'git config' (subkeys separated by dots).\n \n-- \n1.9.4.msysgit.0\n"},{"id":"244329","messageId":"539F38DF.3090004@gmail.com","threadId":"36924","inReplyTo":"1402922952-172-1-git-send-email-philipoakley@iee.org","subject":"Re: [PATCH] doc git: multivar configuration parameters append to existing values","fromName":"Tanay Abhra","fromEmail":"tanayabh@gmail.com","sentAt":"2014-06-16T18:35:11Z","receivedAt":"2014-06-16T18:35:11Z","isPatch":true,"sender":{"key":"tanayabh@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2097229?v=4"},"body":"On 06/16/2014 05:49 AM, Philip Oakley wrote:\n\n> \tPass a configuration parameter to the command. The value\n> -\tgiven will override values from configuration files.\n> +\tgiven will override single valued variables from configuration\n> +\tfiles, and append to multivar variables. Previous multivar values\n\nNit: Forgive me if I am wrong, but `, and` is used for joining two independent\nclauses. It would be better to drop the comma.\n\n> +\tremain in effect. Use \"insteadOf\" style config variables when an\n> +\tover-ride is needed.\n> \tThe is expected in the same format as listed by\n> \t'git config' (subkeys separated by dots).\n> \n> \n\n'insteadOf' is a very specific approach for a general suggestion because it is only\nused in url.*.insteadof in the whole codebase. Also, it has a variation described in\nurls.txt as \"pushinsteadof\". So, if a problem such as mentioned above arises in\na different scenario 'insteadOf' cannot be used in it.\n"},{"id":"244330","messageId":"xmqqd2e8r8yz.fsf@gitster.dls.corp.google.com","threadId":"36924","inReplyTo":"1402922952-172-1-git-send-email-philipoakley@iee.org","subject":"Re: [PATCH] doc git: multivar configuration parameters append to existing values","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-06-16T18:43:32Z","receivedAt":"2014-06-16T18:43:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley writes:\n\n> When the '-c' option is used to pass alternate URLs or similar\n> multivar parameters to git commands the effect is not what the user\n> expected [1,2].\n>\n> Clarify that multivar configuration parameters do not supercede\n> previous values. Suggest an alternative style parameter.\n>\n> [1] http://article.gmane.org/gmane.comp.version-control.git/250427\n> [2] http://article.gmane.org/gmane.comp.version-control.git/251529\n>\n> Signed-off-by: Philip Oakley \n> ---\n> Documentation/git.txt | 5 ++++-\n> 1 file changed, 4 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git.txt b/Documentation/git.txt\n> index 3bd68b0..bedbd76 100644\n> --- a/Documentation/git.txt\n> +++ b/Documentation/git.txt\n> @@ -440,7 +440,10 @@ example the following invocations are equivalent:\n> \n> -c =::\n> \tPass a configuration parameter to the command. The value\n> -\tgiven will override values from configuration files.\n> +\tgiven will override single valued variables from configuration\n> +\tfiles, and append to multivar variables. Previous multivar values\n> +\tremain in effect. Use \"insteadOf\" style config variables when an\n> +\tover-ride is needed.\n> \tThe is expected in the same format as listed by\n> \t'git config' (subkeys separated by dots).\n\nI have two doubts, while appreciating the overall direction to\nclarify things very much.\n\n * \"single overrides, multiple appends\" is not a wrong explanation\n per-se, but sounds like an arbitrary rule that forces people to\n memorize. I wonder if it makes it less burdensome for readers if\n we just said \"Git acts as if the given configuration is specified\n at the very end of the configuration files\"---once the reader\n understands that Git reads all configuration varilables of the\n same name and the code paths that *use* one of them pick the one\n defined the last, it is easy to realize that \"single overrides\"\n is merely a natural consequence of the appending nature of \"-c\".\n\n * The last sentence added, i.e. \"insteadof\"-style, will not be\n understood by any reader other than those who tried to use \"-c\"\n on remote.*.url variables and does not belong here. A better\n way/place to give that information is needed.\n"},{"id":"244339","messageId":"708AD97F308249A1B61D9348AFE59182@PhilipOakley","threadId":"36924","inReplyTo":"xmqqd2e8r8yz.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] doc git: multivar configuration parameters append to existing values","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-06-16T19:38:56Z","receivedAt":"2014-06-16T19:38:56Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \n> Philip Oakley writes:\n>\n>> When the '-c' option is used to pass alternate URLs or similar\n>> multivar parameters to git commands the effect is not what the user\n>> expected [1,2].\n>>\n>> Clarify that multivar configuration parameters do not supercede\n>> previous values. Suggest an alternative style parameter.\n>>\n>> [1] http://article.gmane.org/gmane.comp.version-control.git/250427\n>> [2] http://article.gmane.org/gmane.comp.version-control.git/251529\n>>\n>> Signed-off-by: Philip Oakley \n>> ---\n>> Documentation/git.txt | 5 ++++-\n>> 1 file changed, 4 insertions(+), 1 deletion(-)\n>>\n>> diff --git a/Documentation/git.txt b/Documentation/git.txt\n>> index 3bd68b0..bedbd76 100644\n>> --- a/Documentation/git.txt\n>> +++ b/Documentation/git.txt\n>> @@ -440,7 +440,10 @@ example the following invocations are \n>> equivalent:\n>>\n>> -c =::\n>> Pass a configuration parameter to the command. The value\n>> - given will override values from configuration files.\n>> + given will override single valued variables from configuration\n>> + files, and append to multivar variables. Previous multivar values\n>> + remain in effect. Use \"insteadOf\" style config variables when an\n>> + over-ride is needed.\n>> The is expected in the same format as listed by\n>> 'git config' (subkeys separated by dots).\n>\n> I have two doubts, while appreciating the overall direction to\n> clarify things very much.\n>\n> * \"single overrides, multiple appends\" is not a wrong explanation\n> per-se, but sounds like an arbitrary rule that forces people to\n> memorize.\nAt the time it felt like the most compact method of informing the \nreader.\n\n> I wonder if it makes it less burdensome for readers \n> if\n> we just said \"Git acts as if the given configuration is specified\n> at the very end of the configuration files\"\nI'd started with something like that..\n\n> ---once \n> the reader\n> understands that Git reads all configuration varilables of the\n> same name and the code paths that *use* one of them pick the one\n> defined the last,\nIt's this step that's a concern. We shouldn't be forcing the reader to \nimplicitly grok that, especially as we don't actually say it elsewhere \n(in the regular documentation).\n\n> it is easy to realize that \"single \n> overrides\"\n> is merely a natural consequence of the appending nature of \"-c\".\nPerhaps I should just say that [say it that way].\n>\n> * The last sentence added, i.e. \"insteadof\"-style, will not be\n> understood by any reader other than those who tried to use \"-c\"\n> on remote.*.url variables and does not belong here. A better\n> way/place to give that information is needed.\nI just wanted to indicate that some multivars do have get-out [override] \nconfig parameters, though we aren't consistent about their names yet, \nwhile giving a clue as to a typical name style.\n\nIt would also be good to get feedback from Robert and Ævar on whether \nthe text would actually be informative to them, as they took the time to \nreport the original 'conceptual breakage'.\n\nPhilip \n"},{"id":"244340","messageId":"3757CE4412D345B6BE1E515F8764747D@PhilipOakley","threadId":"36924","inReplyTo":"539F38DF.3090004@gmail.com","subject":"Re: [PATCH] doc git: multivar configuration parameters append to existing values","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-06-16T19:42:42Z","receivedAt":"2014-06-16T19:42:42Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Tanay Abhra\" \n> On 06/16/2014 05:49 AM, Philip Oakley wrote:\n>\n>> Pass a configuration parameter to the command. The value\n>> - given will override values from configuration files.\n>> + given will override single valued variables from configuration\n>> + files, and append to multivar variables. Previous multivar values\n>\n> Nit: Forgive me if I am wrong, but `, and` is used for joining two \n> independent\n> clauses. It would be better to drop the comma.\nI just wrote it in my local style ;-) I was sort of treating them as \nindependent, but see Junio's comments in a similar vein.\n\n>\n>> + remain in effect. Use \"insteadOf\" style config variables when an\n>> + over-ride is needed.\n>> The is expected in the same format as listed by\n>> 'git config' (subkeys separated by dots).\n>>\n>>\n>\n> 'insteadOf' is a very specific approach for a general suggestion \n> because it is only\n> used in url.*.insteadof in the whole codebase. Also, it has a \n> variation described in\n> urls.txt as \"pushinsteadof\". So, if a problem such as mentioned above \n> arises in\n> a different scenario 'insteadOf' cannot be used in it.\nI was using it as a suggestion for the user's 'go look for an \nalternative' step (i.e. that there may be an alternative!)\n\n--\nPhilip \n"},{"id":"244341","messageId":"20140616194849.GA24376@sigill.intra.peff.net","threadId":"36924","inReplyTo":"xmqqd2e8r8yz.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] doc git: multivar configuration parameters append to existing values","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2014-06-16T19:48:49Z","receivedAt":"2014-06-16T19:48:49Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Jun 16, 2014 at 11:43:32AM -0700, Junio C Hamano wrote:\n\n> I have two doubts, while appreciating the overall direction to\n> clarify things very much.\n> \n> * \"single overrides, multiple appends\" is not a wrong explanation\n> per-se, but sounds like an arbitrary rule that forces people to\n> memorize. I wonder if it makes it less burdensome for readers if\n> we just said \"Git acts as if the given configuration is specified\n> at the very end of the configuration files\"---once the reader\n> understands that Git reads all configuration varilables of the\n> same name and the code paths that *use* one of them pick the one\n> defined the last, it is easy to realize that \"single overrides\"\n> is merely a natural consequence of the appending nature of \"-c\".\n\nYeah, I think the problem is really not one of \"-c\" in particular. If\nyou did:\n\n git config --system remote.magic.url some-default\n\nto provide a universal alias for the \"magic\" remote, you could not\noverride it via ~/.gitconfig or .git/config, for the same reasons.\n\nI think we need a better discussion of multivar versus \"normal\"\noverridable variables in config.txt, and then \"-c\" can make a note that\nthis is a potential issue, and refer readers to the right section.\n\nI also think it would be nice to have a syntax to \"reset\" multivars to\ntheir initial state (both from config files and from \"-c\"). Their\ninability to be overridden is one of the reasons we have so few of them.\n\n> * The last sentence added, i.e. \"insteadof\"-style, will not be\n> understood by any reader other than those who tried to use \"-c\"\n> on remote.*.url variables and does not belong here. A better\n> way/place to give that information is needed.\n\nAgreed. I think that could go in the discussion I mentioned above (as\n\"some variables have other mechanisms to accomplish the same thing,\nlike...\"). But if we learned a mechanism for resetting multivars, such\nworkarounds would not be needed at all.\n\n-Peff\n"},{"id":"244357","messageId":"xmqqfvj4pnl1.fsf@gitster.dls.corp.google.com","threadId":"36924","inReplyTo":"708AD97F308249A1B61D9348AFE59182@PhilipOakley","subject":"Re: [PATCH] doc git: multivar configuration parameters append to existing values","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-06-16T21:10:50Z","receivedAt":"2014-06-16T21:10:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" writes:\n\n>> ---once \n>> the reader\n>> understands that Git reads all configuration varilables of the\n>> same name and the code paths that *use* one of them pick the one\n>> defined the last,\n> It's this step that's a concern. We shouldn't be forcing the reader to \n> implicitly grok that, especially as we don't actually say it elsewhere \n> (in the regular documentation).\n\nI think that is what I was driving at. If we do not tell the reader\nthat, perhaps we should and everything else will fall as natural\nconsequence of that understanding.\n\n>> * The last sentence added, i.e. \"insteadof\"-style, will not be\n>> understood by any reader other than those who tried to use \"-c\"\n>> on remote.*.url variables and does not belong here. A better\n>> way/place to give that information is needed.\n>\n> I just wanted to indicate that some multivars do have get-out [override] \n> config parameters, though we aren't consistent about their names yet, \n> while giving a clue as to a typical name style.\n\nI think those who tried \"-c remote.*.url\" would be helped better by\nhaving a see-also in the documentation on \"remote.*.url\" that refers\nthem to \"insteadOf\" noting that \"remote.*.url\" is a multi-value\nvariable and appending different definition will not make \"the last\none wins\". After all \"-c\" is merely *one* way to append.\n\nThe next person who gets confused may say \"I added remote.origin.url\nat the end of my $repo/.git/config expecting that the value to be\nused\"; the answer would be the same \"the variable is multi-valued;\nadding a new value is not the right way to futz with it. You either\nneed to replace, or if you do not want to replace, use insteadOf\".\n\nThat is the second reason why the mention of insteadOf does not\nbelong to the description of \"-c var=value\".\n\nPerhaps something like this as a starting point?\n\n Documentation/config.txt | 11 +++++++++++\n 1 file changed, 11 insertions(+)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex 1d718bd..357cc02 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -2108,6 +2108,13 @@ remote.pushdefault::\n remote..url::\n \tThe URL of a remote repository. See linkgit:git-fetch[1] or\n \tlinkgit:git-push[1].\n++\n+Note that this variable is multi-valued (e.g. \"git push there\" with\n+multiple `remote.there.url` will push to all the named repositories),\n+and does not follow the \"last-one-survives\" rule. When you want to\n+temporarily redirect a push to somewhere else, see `url..insteadOf`;\n+you cannot use \"git -c remote..url= push\", because\n+you will be pushing to both the configured place and the temporary place.\n \n remote..pushurl::\n \tThe push URL of a remote repository. See linkgit:git-push[1].\n@@ -2419,6 +2426,10 @@ url..insteadOf::\n \tthe best alternative for the particular user, even for a\n \tnever-before-seen repository on the site. When more than one\n \tinsteadOf strings match a given URL, the longest match is used.\n++\n+When you want to redirect a push to `$URL` (e.g. `site.xz:myrepo`) \n+temporarily to somewhere else (e.g. `othersite.xz:myrepo`), you can\n+use \"git -c url.othersite.xz:myrepo.insteadOf=site.xz:myrepo push ...\"\n \n url..pushInsteadOf::\n \tAny URL that starts with this value will not be pushed to;\n"},{"id":"244491","messageId":"E9A1113CB95B406FA3C16ED2AA5B111D@PhilipOakley","threadId":"36924","inReplyTo":"xmqqfvj4pnl1.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] doc git: multivar configuration parameters append to existing values","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-06-17T22:03:14Z","receivedAt":"2014-06-17T22:03:14Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \n> \"Philip Oakley\" writes:\n>\n>>> ---once\n>>> the reader\n>>> understands that Git reads all configuration varilables of the\n>>> same name and the code paths that *use* one of them pick the one\n>>> defined the last,\n>> It's this step that's a concern. We shouldn't be forcing the reader\n>> to\n>> implicitly grok that, especially as we don't actually say it\n>> elsewhere\n>> (in the regular documentation).\n>\n> I think that is what I was driving at. If we do not tell the reader\n> that, perhaps we should and everything else will fall as natural\n> consequence of that understanding.\n>\n>>> * The last sentence added, i.e. \"insteadof\"-style, will not be\n>>> understood by any reader other than those who tried to use \"-c\"\n>>> on remote.*.url variables and does not belong here. A better\n>>> way/place to give that information is needed.\n>>\n>> I just wanted to indicate that some multivars do have get-out\n>> [override]\n>> config parameters, though we aren't consistent about their names yet,\n>> while giving a clue as to a typical name style.\n>\n> I think those who tried \"-c remote.*.url\" would be helped better by\n> having a see-also in the documentation on \"remote.*.url\" that refers\n> them to \"insteadOf\" noting that \"remote.*.url\" is a multi-value\n> variable and appending different definition will not make \"the last\n> one wins\". After all \"-c\" is merely *one* way to append.\n>\n> The next person who gets confused may say \"I added remote.origin.url\n> at the end of my $repo/.git/config expecting that the value to be\n> used\"; the answer would be the same \"the variable is multi-valued;\n> adding a new value is not the right way to futz with it. You either\n> need to replace, or if you do not want to replace, use insteadOf\".\n>\n> That is the second reason why the mention of insteadOf does not\n> belong to the description of \"-c var=value\".\n>\n> Perhaps something like this as a starting point?\n>\n\nYes, that's a good start, but we still need the correction to the git(1)\n'-c' option text.\n\nIt'll be a few days before I can get back to this.\n\n> Documentation/config.txt | 11 +++++++++++\n> 1 file changed, 11 insertions(+)\n>\n> diff --git a/Documentation/config.txt b/Documentation/config.txt\n> index 1d718bd..357cc02 100644\n> --- a/Documentation/config.txt\n> +++ b/Documentation/config.txt\n> @@ -2108,6 +2108,13 @@ remote.pushdefault::\n> remote..url::\n> The URL of a remote repository. See linkgit:git-fetch[1] or\n> linkgit:git-push[1].\n> ++\n> +Note that this variable is multi-valued (e.g. \"git push there\" with\n> +multiple `remote.there.url` will push to all the named repositories),\n> +and does not follow the \"last-one-survives\" rule. When you want to\n> +temporarily redirect a push to somewhere else, see\n> `url..insteadOf`;\n> +you cannot use \"git -c remote..url= push\",\n> because\n> +you will be pushing to both the configured place and the temporary\n> place.\n>\n> remote..pushurl::\n> The push URL of a remote repository. See linkgit:git-push[1].\n> @@ -2419,6 +2426,10 @@ url..insteadOf::\n> the best alternative for the particular user, even for a\n> never-before-seen repository on the site. When more than one\n> insteadOf strings match a given URL, the longest match is used.\n> ++\n> +When you want to redirect a push to `$URL` (e.g. `site.xz:myrepo`)\n> +temporarily to somewhere else (e.g. `othersite.xz:myrepo`), you can\n> +use \"git -c url.othersite.xz:myrepo.insteadOf=site.xz:myrepo push\n> ...\"\n>\n> url..pushInsteadOf::\n> Any URL that starts with this value will not be pushed to;\n>\n>\n--\nPhilip\n"}]}