Re: [PATCH] doc: option value may be separate for valid reasons

[Junio C Hamano <gitster@pobox.com>]

Eric Sunshine <sunshine@sunshineco.com> writes:

>> +   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.

Probably.

>> 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

You're right.  That reads much better.

Thanks.