From: "Junio C Hamano" <gits...@pobox.com>
Philip Oakley <philipoak...@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 <philipoak...@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.
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 majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Reply via email to