[PATCH 1/2] gitcredentials(7): clarify quoting of helper examples

From: Jeff King <peff@peff.net>
To: Junio C Hamano <gitster@pobox.com>
Cc: douglas.fuller@gmail.com, git@vger.kernel.org
Subject: [PATCH 1/2] gitcredentials(7): clarify quoting of helper examples
Date: Fri, 1 May 2020 02:20:39 -0400	[thread overview]
Message-ID: <20200501062039.GA25603@coredump.intra.peff.net> (raw)
In-Reply-To: <20200501061917.GC23665@coredump.intra.peff.net>

We give several helper config examples, but don't make clear that these
are raw values. It's up to the user to add the appropriate quoting to
put them into a config file (either by running with "git config" and
quoting against the shell, or by adding double-quotes as appropriate
within the git-config file).

Let's flesh them out as full config blocks, which makes the syntax more
clear (and makes it possible for people to just cut-and-paste them as a
starting point). I added double-quotes to any values larger than a
single word. That isn't strictly necessary in all cases, but it
sidesteps explaining the rules about exactly when you need to quote a
value.

The existing quotes can be converted to single-quotes in one instance,
and simply omitted in another for simplicity (unless you have odd
whitespace in your password, the shell whitespace-splitting behavior is
fine). I also swapped out backticks for our preferred $().

Reported-by: douglas.fuller@gmail.com
Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/gitcredentials.txt | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt
index 1814d2d23c..8a20343dd7 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.
-- 
2.26.2.933.gdf62622942

