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