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

From: Christian Couder <christian.couder@gmail.com>
Date: Apr 2, 2014, 06:01 UTC
Message-ID: <CAP8UFD1hrXDdwKokLH_j=vwWoViC9sSJHf0gTFubh-oFQao4MA@mail.gmail.com>
In-Reply-To: <20140402003938.GE6851@google.com>

Hi,

On Wed, Apr 2, 2014 at 2:39 AM, Jonathan Nieder <jrnieder@gmail.com> wrote:

Show 14 quoted lines

> (culling cc list)
> Hi,
>
> Christian Couder wrote:
>
>> [Subject: Documentation: add documentation for 'git interpret-trailers']
>>
>> Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
>
> This should be squashed into the patch that introduces the
> interpret-trailers command, IMHO (or if it should be reviewed
> separately, it can be an earlier patch).  That way, someone looking at
> when the command was introduced and wanting to understand what it was
> originally meant to do has the information close by.

Well, the series is not very long, so this patch is quite close to the beginning anyway.

Show 37 quoted lines

> Thanks for picking up the 'git commit --fixes' topic and your steady
> work improving the series.
>
> [...]
>> --- /dev/null
>> +++ b/Documentation/git-interpret-trailers.txt
>> @@ -0,0 +1,123 @@
>> +git-interpret-trailers(1)
>> +=========================
>> +
>> +NAME
>> +----
>> +git-interpret-trailers - help add stuctured information into commit messages
>> +
>> +SYNOPSIS
>> +--------
>> +[verse]
>> +'git interpret-trailers' [--trim-empty] [(<token>[(=|:)<value>])...]
>> +
>> +DESCRIPTION
>> +-----------
>> +Help add RFC 822-like headers, called 'trailers', at the end of the
>> +otherwise free-form part of a commit message.
>> +
>> +This command is a filter. It reads the standard input for a commit
>> +message and applies the `token` arguments, if any, to this
>> +message. The resulting message is emited on the standard output.
>
> Do you have an example?  Does it work like this?
>
>         $ git interpret-trailers 'signoff=Jonathan Nieder <jrnieder@gmail.com>' <<EOF
>         > foo bar baz qux
>         > EOF
>         foo bar baz qux
>
>         Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
>         $

Yeah, that's the idea. But you need to run something like:

$ git config trailer.signoff.key "Signed-off-by:"

to configure it properly first.

By the way trying your example, I found that it is not currently adding an empty line before the s-o-b. I will have a look.

> A short EXAMPLES section could help.

Yeah, it is planned, but not yet implemented, as written in patch 0/11:

"The following features are planned but not yet implemented:
        - add more tests related to commands
        - add examples in documentation
        - integration with "git commit""

> If I am understanding it correctly, would a name like 'git add-trailers'
> work?

It could work but it can modify, not just add trailers.

> How do I read back the trailers later?

Why do you want to read them back? Right now it should be used in hooks to modify commit messages.

Show 6 quoted lines

> [...]
>> +By default, a 'token=value' or 'token:value' argument will be added
>> +only if
>
> 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. 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.

Thanks, Christian.