Re: [PATCH] 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.
>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
> diff --git c/Documentation/gitcli.txt w/Documentation/gitcli.txt
> @@ -88,10 +88,20 @@ scripting Git:
> + * 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 credential-store
> +   --file ~/sec/rit`, not `git credential-store --file=~/sec/rit`.
> +   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 internally,
> +   but not all.  The `--file` option of `credential-store` is an
> +   example that it needs shell's help to tilde-expand its value.

> diff --git c/Documentation/gitcredentials.txt w/Documentation/gitcredentials.txt
> @@ -240,10 +240,15 @@ Here are some example specifications:
>  # the arguments are parsed by the shell, so use shell
>  # quoting if necessary
>  [credential]
>         helper = "foo --bar='whitespace arg'"
>
> +# store helper (discouraged) with custom location for the db file;
> +# tilde expansion often requires the filename as a separate argument.
> +[credential]
> +       helper = "store --file ~/.git-secret.txt"