Re: [PATCH v3 17/17] Documentation: add documentation for 'git interpret-trailers'

[Christian Couder <chriscool@tuxfamily.org>]

From: Eric Sunshine <sunshine@sunshineco.com>
>
> On Sun, Jan 26, 2014 at 12:00 PM, Christian Couder
> <chriscool@tuxfamily.org> wrote:
>> Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
>> ---
>> diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
>> new file mode 100644
>> index 0000000..f74843e
>> --- /dev/null
>> +++ b/Documentation/git-interpret-trailers.txt
>> @@ -0,0 +1,137 @@
>> +git-interpret-trailers(1)
>> +=========================
>> +
>> +NAME
>> +----
>> +git-interpret-trailers - help add stuctured information into commit messages
>> +
>> +SYNOPSIS
>> +--------
>> +[verse]
>> +'git interpret-trailers' [--trim-empty] [--infile=file] [<token[=value]>...]
> 
> Would it be more consistent with existing documentation to format this as so?
> 
>   [--infile=<file>] [<token>[=<value>]]...

No, it would be very inconsistent:

$ grep '\.\.\.\]' *.txt | wc -l
103
$ grep '\]\.\.\.' *.txt | wc -l
0

>> +DESCRIPTION
>> +-----------
>> +Help add RFC 822 like headers, called 'trailers', at the end of the
> 
> s/822 like/822-like/

Ok.

> Was the suggestion, early in the discussion, to use "footer" rather
> than "trailer" dismissed?

During the early discussions people initially talked about "footer"
while Junio and others talked about "trailer".

See:

http://thread.gmane.org/gmane.comp.version-control.git/236429/
http://thread.gmane.org/gmane.comp.version-control.git/236770/

I have no preference for one or the other, but by default I use what
Junio uses.

>> +otherwise free-form part of a commit message.
>> +
>> +Unless `--infile=file` is used, this command is a filter. It reads the
>> +standard input for a commit message and apply the `token` arguments,
> 
> s/apply/applies/

Ok.

>> +if any, to this message. The resulting message is emited on the
>> +standard output.
>> +
>> +Some configuration variables control the way the `token` arguments are
>> +applied to the message and the way any existing trailer in the message
>> +is changed. They also make it possible to automatically add some
>> +trailers.
>> +
>> +By default, a 'token=value' or 'token:value' argument will be added
>> +only if no trailer with the same (token, value) pair is already in the
>> +message. The 'token' and 'value' parts will be trimmed to remove
>> +starting and trailing white spaces, and the resulting trimmed 'token'
> 
> Other git documentation uniformly spells it as "whitespace" rather
> than "white spaces".

You are right I will change that.

>> +and 'value' will appear in the message like this:
>> +
>> +------------------------------------------------
>> +token: value
>> +------------------------------------------------
>> +
>> +By default, if there are already trailers with the same 'token' the
>> +trailer will appear just after the last trailer with the same
> 
> It might be a bit clearer to say "the _new_ trailer will appear...".

Ok.

>> +'token'. Otherwise it will appear at the end of the message.
>> +
>> +Note that 'trailers' do not follow and are not intended to follow many
>> +rules that are in RFC 822. For example they do not follow the line
>> +breaking rules, the encoding rules and probably many other rules.
>> +
>> +Trailers have become a de facto standard way to add helpful structured
>> +information into commit messages. For example the well known
>> +"Signed-off-by: " trailer is used by many projects like the Linux
>> +kernel and Git.
> 
> This "justification" paragraph might make more sense near or at the
> very the top of the Description section.

Yeah, or maybe I can remove it entirely.

>> +OPTIONS
>> +-------
>> +--trim-empty::
>> +       If the 'value' part of any trailer contains onlywhite spaces,
> 
> s/onlywhite spaces/only whitespace/

Ok.

>> +       the whole trailer will be removed from the resulting message.
>> +
>> +----infile=file::
>> +       Read the commit message from `file` instead of the standard
>> +       input.
>> +
>> +CONFIGURATION VARIABLES
>> +-----------------------
>> +
>> +trailer.<token>.key::
>> +       This 'key' will be used instead of 'token' in the
>> +       trailer. After some alphanumeric characters, it can contain
>> +       some non alphanumeric characters like ':', '=' or '#' that will
>> +       be used instead of ':' to separate the token from the value in
>> +       the trailer, though the default ':' is more standard.
>> +
>> +trailer.<token>.where::
>> +       This can be either `after`, which is the default, or
>> +       `before`. If it is `before`, then a trailer with the specified
>> +       token, will appear before, instead of after, other trailers
>> +       with the same token, or otherwise at the beginning, instead of
>> +       at the end, of all the trailers.
>> +
>> +trailer.<token>.ifexist::
>> +       This option makes it possible to chose what action will be
> 
> s/chose/choose/

Ok.

>> +       performed when there is already at least one trailer with the
>> +       same token in the message.
>> ++
>> +The valid values for this option are: `addIfDifferent` (this is the
>> +default), `addIfDifferentNeighbor`, `add`, `overwrite` or `doNothing`.
>> ++
>> +With `addIfDifferent`, a new trailer will be added only if no trailer
>> +with the same (token, value) pair is already in the message.
>> ++
>> +With `addIfDifferentNeighbor`, a new trailer will be added only if no
>> +trailer with the same (token, value) pair is above or below the line
>> +where the new trailer will be added.
>> ++
>> +With `add`, a new trailer will be added, even if some trailers with
>> +the same (token, value) pair are already in the message.
>> ++
>> +With `overwrite`, the new trailer will overwrite an existing trailer
>> +with the same token.
>> ++
>> +With `doNothing`, nothing will be done, that is no new trailer will be
>> +added if there is already one with the same token in the message.
>> +
>> +trailer.<token>.ifmissing::
>> +       This option makes it possible to chose what action will be
> 
> s/chose/choose/

Ok.

>> +       performed when there is not yet any trailer with the same
>> +       token in the message.
>> ++
>> +The valid values for this option are: `add` (this is the default) and
>> +`doNothing`.
>> ++
>> +With `add`, a new trailer will be added.
>> ++
>> +With `doNothing`, nothing will be done.
>> +
>> +trailer.<token>.command::
>> +       This option can be used to specify a shell command that will
>> +       be used to automatically add or modify a trailer with the
>> +       specified 'token'.
>> ++
>> +When this option is specified, it is like if a special 'token=value'
>> +argument is added at the end of the command line, where 'value' will
>> +be given by the standard output of the specified command.
> 
> What happens if the text returned by the command has multiple lines?

The 'value' part of trailer will be on multiple lines.

> Should the documentation say something about this?

I think it is better left as unspecified because we might want to
print a warning, or perhaps error out in this case.

Thanks,
Christian.