Skip to content

Commit 1bc1e94

Browse files
committed
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 <[email protected]> Signed-off-by: Junio C Hamano <[email protected]>
1 parent f1a3844 commit 1bc1e94

File tree

2 files changed

+15
-0
lines changed

2 files changed

+15
-0
lines changed

Documentation/gitcli.txt

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,15 @@ scripting Git:
9090
for long options. An option that takes optional option-argument must be
9191
written in the 'stuck' form.
9292

93+
* Despite the above suggestion, when Arg is a path relative to the
94+
home directory of a user, e.g. ~/directory/file or ~u/d/f, you
95+
may want to use the separate form, e.g. `git foo --file ~/mine`,
96+
not `git foo --file=~/mine`. The shell will expand `~/` in the
97+
former to your home directory, but most shells keep the tilde in
98+
the latter. Some of our commands know how to tilde-expand the
99+
option value even when given in the stuck form, but not all of
100+
them do.
101+
93102
* When you give a revision parameter to a command, make sure the parameter is
94103
not ambiguous with a name of a file in the work tree. E.g. do not write
95104
`git log -1 HEAD` but write `git log -1 HEAD --`; the former will not work

Documentation/gitcredentials.txt

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -242,6 +242,12 @@ Here are some example specifications:
242242
[credential]
243243
helper = "foo --bar='whitespace arg'"
244244

245+
# store helper (discouraged) with custom location for the db file;
246+
# use `--file ~/.git-secret.txt`, rather than `--file=~/.git-secret.txt`,
247+
# to allow the shell to expand tilde to the home directory.
248+
[credential]
249+
helper = "store --file ~/.git-secret.txt"
250+
245251
# you can also use an absolute path, which will not use the git wrapper
246252
[credential]
247253
helper = "/path/to/my/helper --with-arguments"

0 commit comments

Comments
 (0)