On Sun, Nov 24, 2024 at 4:44 AM Junio C Hamano <gitster@xxxxxxxxx> wrote:
> 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@xxxxxxxxx>
> ---
> 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.
I'm not sure the final sentence adds any value considering that
credential-store was already mentioned in the example earlier in the
paragraph, though I suppose it doesn't hurt to keep the sentence.
> 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"
In the context of the commit message, I understand why you added the
comment above this example, but as a mere user without having that
context, I think the part starting "tilde expansion..." would confuse
me more than help. Perhaps being a bit more explicit might help:
# use `--file ~/path` rather than `--file=~/path` to allow the
# shell to expand tilde to the home directory
