On Thu, Apr 30, 2020 at 11:09:02AM -0700, Junio C Hamano wrote:
> [...]
> Having said all that, I think we should clarify what these sample
> strings are in the introductory text in the examples.
You already said everything I was going to. :)
> I've always thought that they are illustrating possible values and
> how to express that value in the context the values appear in is up
> to the readers who learn what values to write in this document (and
> they learn from manual for shell to learn the shell quoting
> convention and manual for 'git config' to learn the config quoting
> convention). Hence my initial reaction to your patch was "shell?
> Quoting for shell is outside the scope of the explanation here".
>
> On the other hand, for anybody who assumes that these examples are
> literally showing what you write after "[credential] helper = " in
> the configuration file, the example clearly is wrong and dq may be
> needed (but yours is also wrong, in that it loses double quotes
> around the argument to echo; if ~/.secret file had a tab in it, the
> helper will now yield a wrong password and you won't be able to log
> in).
Yes, they were definitely meant as: here are the raw values you would
want to use, and it is up to you to figure out how to get that into a
config file (whether on the cmdline via "git config" or editing the file
yourself).
I think we can either clarify that with a note at the beginning of the
list, or we can just present it as config, like:
diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt
index 1814d2d23c..c756ecb8fd 100644
--- a/Documentation/gitcredentials.txt
+++ b/Documentation/gitcredentials.txt
@@ -216,20 +216,25 @@ Here are some example specifications:
----------------------------------------------------
# run "git credential-foo"
-foo
+[credential]
+helper = foo
# same as above, but pass an argument to the helper
-foo --bar=baz
+[credential]
+helper = foo --bar=baz
# the arguments are parsed by the shell, so use shell
# quoting if necessary
-foo --bar="whitespace arg"
+[credential]
+helper = "foo --bar='whitespace arg'"
# you can also use an absolute path, which will not use the git wrapper
-/path/to/my/helper --with-arguments
+[credential]
+helper = /path/to/my/helper --with-arguments
# or you can specify your own shell snippet
-!f() { echo "password=`cat $HOME/.secret`"; }; f
+[credential]
+helper = "!f() { echo \"password=`cat $HOME/.secret`\"; }; f"
----------------------------------------------------
Generally speaking, rule (3) above is the simplest for users to specify.
It may be easier to just use double-quotes consistently, even for ones
that do not need it, to give readers one less thing to wonder about.
-Peff
