Re: [PATCH] doc: fix quoting bug in credential cache example

From: Jeff King <peff@peff.net>
Date: May 1, 2020, 05:57 UTC
Message-ID: <20200501055738.GB23665@coredump.intra.peff.net>
In-Reply-To: <xmqqr1w4sv5t.fsf@gitster.c.googlers.com>

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. :)

Show 15 quoted lines

> 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