Re: [PATCH v9 11/11] Documentation: add documentation for 'git interpret-trailers'

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

Christian Couder <chriscool@tuxfamily.org> writes:

> From: Junio C Hamano <gitster@pobox.com>
>>
>> A different way to sell a colon, e.g.
>> 
>>     Consider the instruction sed takes on its command line.
>>     (e.g. "sed 's/frotz/nitfol/' <xyzzy").  In the most general
>>     form, you would always give it as the value of an '-e' option
>>     (e.g. "sed -e 's/frotz/nitfol' <xyzzy"), but you are allowed to
>>     be loose in limited occassions.  "Key:value" is like that, and
>>     in the most general form, it actually needs to be spelled as
>>     "-e 'Key:value'".
>> 
>> is possible, but I do not think it is a particularly good analogy,
>> because what you have as the alternative is "Key=value", and not
>> "-e 'Key:value'", or "--Key=value" (the last would probably be the 
>> most natural way to express this).
>
> The analogy that I would use is rather that Perl lets people use
> 's:foo:bar:' as well as 's=foo=bar=' instead of 's/foo/bar/' if they
> prefer.

I could *almost* buy that, but that does not hold as you are not
allowing (and I do not think you need to in this case) the user to
pick any termination character like "s|foo|bar|".  The only thing
you are doing is forbidding both ":" and "=" from the set of allowed
characters for labels.

However.

I think we could buy the syntax if the "Key:value" form were the
*only* form, *without* accepting "Key=value".

The latter is a poor attempt to pretend as if it is a normal command
line option, but because that form does not even take double-dashes
at the beginning, it even fails to mimic as a command line option.

It would be one way to reduce the unnecessary cognitive load from
the users when learning the Git command line argument convention to
reject the "key=value" form and only stick to "key: value" form.
After all, because of the shape of the footer we add to the log
message (i.e. a keyword label followed by a colon followed by a SP
followed by the value), it is clear that we can use ":" as the
separator without inconveniencing the users who want to use some
unusual characters in the label part, but there is no strong reason
to reject an equal sign in the label.