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

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 7, 2014, 16:52 UTC
Message-ID: <xmqq4n25nkt0.fsf@gitster.dls.corp.google.com>
In-Reply-To: <CAP8UFD38TE=5zxvkDvLRsDTpC6zDo6EN5q_HJMQPbUBcfJVsSg@mail.gmail.com>

Christian Couder <christian.couder@gmail.com> writes:

Show 16 quoted lines

> On Sat, Apr 5, 2014 at 12:42 AM, Junio C Hamano <gitster@pobox.com> wrote:
>> Junio C Hamano <gitster@pobox.com> writes:
>>
>>> Christian Couder <christian.couder@gmail.com> writes:
>>> "The following features are planned but not yet implemented:
>>>         - add more tests related to commands
>>>         - add examples in documentation
>>>         - integration with "git commit""
>>
>> I was planning to merge the series to 'next', but perhaps we should
>> wait at least for the first two items (I do not think the third one
>> is necessary to block the series).
>
> I will send soon a new version of the series with more tests and fixes.
> It will also contains a patch that adds an empty line before the
> trailers in the output if there is not already one.

Ah, yes, that one was mentioned in the reviews, I remember.

> After that I plan to work on adding examples to the documentation.

OK, thanks.

> First accepting both ':' and '=' means one can see the "git
> interpret-trailers" as acting on trailers only. Not just on trailers
> from the intput message and option parameters from the command line.

Sorry, you lost me. What does "acting on trailers only" really mean? Do you mean the command should/can be run without any command line options, pick up the existing "Signed-off-by:" and friends in its input and emit its output, somehow taking these existing ones as its instruction regarding how to transform the input to its output?

Show 9 quoted lines

> And second there is also a practical advantage, as the user can
> copy-paste trailers directly from other messages into the command line
> to pass them as arguments to "git interpret-trailers" without the need
> to replace the ':' with '='. Even if this command is not often used
> directly by users, it might simplify scripts using it.
>
> Third there is a technical advantage which is that the code that
> parses arguments from the command line can be the same as the code
> that parses trailers from the input message.

I do not see these two as valid arguments to make the command line more complex to the end users---who now need to know that only this command treats its command line in a funny way, accepting a colon in place of an equal sign.

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