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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Hi,

On Wed, Apr 2, 2014 at 2:39 AM, Jonathan Nieder <jrnieder@xxxxxxxxx> wrote:
> (culling cc list)
> Hi,
>
> Christian Couder wrote:
>
>> [Subject: Documentation: add documentation for 'git interpret-trailers']
>>
>> Signed-off-by: Christian Couder <chriscool@xxxxxxxxxxxxx>
>
> 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.

> 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@xxxxxxxxx>' <<EOF
>         > foo bar baz qux
>         > EOF
>         foo bar baz qux
>
>         Signed-off-by: Jonathan Nieder <jrnieder@xxxxxxxxx>
>         $

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.

> [...]
>> +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.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html




[Index of Archives]     [Linux Kernel Development]     [Gcc Help]     [IETF Annouce]     [DCCP]     [Netdev]     [Networking]     [Security]     [V4L]     [Bugtraq]     [Yosemite]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Linux SCSI]     [Fedora Users]