doc: option value may be separate for valid reasons

Even though `git help cli` recommends users to prefer using
"--option=value" over "--option value", there can be reasons why
giving them separately is a good idea.  One reason is that shells do
not perform tilde expansion for `--option=~/path/name` but they
expand `--options ~/path/name` just fine.

This is not a problem for many options whose option parsing is
properly written using OPT_FILENAME(), because the value given to
OPT_FILENAME() is tilde-expanded internally by us, but some commands
take a pathname as a mere string, which needs this trick to have the
shell help us.

I think the reason we originally decided to recommend the stuck form
was because an option that takes an optional value requires you to
use it in the stuck form, and it is one less thing for users to
worry about if they get into the habit to always use the stuck form.
But we should be discouraging ourselves from adding an option with
an optional value in the first place, and we might want to weaken
the current recommendation.

In any case, let's describe this one case where it is necessary to
use the separate form, with an example.

Reviewed-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
index 7c709324ba904efe5f6a544086c767fbc1ab7cb4..bd62cbd0439508f7041526b1f434801da53ed3f3 100644 (file)
--- a/Documentation/gitcli.txt
+++ b/Documentation/gitcli.txt
@@ -90,6 +90,15 @@ scripting Git:
    for long options.  An option that takes optional option-argument must be
    written in the 'stuck' form.
 
+ * Despite the above suggestion, when Arg is a path relative to the
+   home directory of a user, e.g. ~/directory/file or ~u/d/f, you
+   may want to use the separate form, e.g. `git foo --file ~/mine`,
+   not `git foo --file=~/mine`.  The shell will expand `~/` in the
+   former to your home directory, but most shells keep the tilde in
+   the latter.  Some of our commands know how to tilde-expand the
+   option value even when given in the stuck form, but not all of
+   them do.
+
  * When you give a revision parameter to a command, make sure the parameter is
    not ambiguous with a name of a file in the work tree.  E.g. do not write
    `git log -1 HEAD` but write `git log -1 HEAD --`; the former will not work

diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt
index 71dd19731af0dfb187ac55b15826e6b4b3e887b6..35a7452c8fe3cca7e972483f279adcc80b7c91da 100644 (file)
--- a/Documentation/gitcredentials.txt
+++ b/Documentation/gitcredentials.txt
@@ -242,6 +242,12 @@ Here are some example specifications:
 [credential]
        helper = "foo --bar='whitespace arg'"
 
+# store helper (discouraged) with custom location for the db file;
+# use `--file ~/.git-secret.txt`, rather than `--file=~/.git-secret.txt`,
+# to allow the shell to expand tilde to the home directory.
+[credential]
+       helper = "store --file ~/.git-secret.txt"
+
 # you can also use an absolute path, which will not use the git wrapper
 [credential]
        helper = "/path/to/my/helper --with-arguments"