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

From: Christian Couder <christian.couder@gmail.com>
Date: Apr 7, 2014, 09:39 UTC
Message-ID: <CAP8UFD38TE=5zxvkDvLRsDTpC6zDo6EN5q_HJMQPbUBcfJVsSg@mail.gmail.com>
In-Reply-To: <xmqqk3b4ogwu.fsf@gitster.dls.corp.google.com>

On Sat, Apr 5, 2014 at 12:42 AM, Junio C Hamano <gitster@pobox.com> wrote:

Show 11 quoted lines

> 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. After that I plan to work on adding examples to the documentation.

Show 22 quoted lines

>>> Why support both '=' and ':'?  Using just one would make it easier to
>>> grep through scripts to see who is adding signoffs.
>>
>> That was already discussed previously.
>
> I do recall it was discussed previously, but given that a new reader
> posed the same question, I am not sure if the end result in this
> patch under discussion sufficiently answers the question in a
> satisfactory way.
>
>> The reason is that people are used to "token=value" for command line
>> arguments, but trailers appears in the result as "token: value", so it
>> is better for the user if we support both.
>
> While I do understand the part before ", so" on the second line, I
> do not see why that leads to the conclusion at all.
>
> Yes, because it is a well-established convention to separate option
> name with its parameter with '=', accepting "--option=parameter"
> makes sense.  That may result in a string "Option: parameter" added
> to the output from the command.  I am not sure why that output has
> anything to do with how the command line should be specified.

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. But from trailers both from the input message and being passed as arguments. In my opinion it is good if it can be seen this way, as it may simplifies the user's mental model of how the command works.

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.

Thanks, Christian.