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

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 7, 2014, 22:00 UTC
Message-ID: <xmqqr458ls0k.fsf@gitster.dls.corp.google.com>
In-Reply-To: <20140407.205800.839733420387302333.chriscool@tuxfamily.org>

Christian Couder <chriscool@tuxfamily.org> writes:

Show 20 quoted lines

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