From: "Junio C Hamano" <gitster@xxxxxxxxx>
Philip Oakley <philipoakley@xxxxxxx> 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@xxxxxxx>
---
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..
---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].
* 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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html