On 14-08-16 12:06 PM, Christian Couder wrote:
> While at it add git-interpret-trailers to "command-list.txt".
> Signed-off-by: Christian Couder <chrisc...@tuxfamily.org>
> Signed-off-by: Junio C Hamano <gits...@pobox.com>
> Documentation/git-interpret-trailers.txt | 308
> command-list.txt | 1 +
> 2 files changed, 309 insertions(+)
> create mode 100644 Documentation/git-interpret-trailers.txt
> diff --git a/Documentation/git-interpret-trailers.txt
> new file mode 100644
> index 0000000..cf5b194
> --- /dev/null
> +++ b/Documentation/git-interpret-trailers.txt
> @@ -0,0 +1,308 @@
> +git-interpret-trailers - help add stuctured information into commit messages
> +'git interpret-trailers' [--trim-empty] [(--trailer
> <token>[(=|:)<value>])...] [<file>...]
> +Help adding 'trailers' lines, that look similar to RFC 822 e-mail
> +headers, at the end of the otherwise free-form part of a commit
> +This command reads some patches or commit messages from either the
> +<file> arguments or the standard input if no <file> is specified. Then
> +this command applies the arguments passed using the `--trailer`
> +option, if any, to the commit message part of each input file. The
> +result is emitted on the standard output.
> +Some configuration variables control the way the `--trailer` arguments
> +are applied to each commit message and the way any existing trailer in
> +the commit message is changed. They also make it possible to
> +automatically add some trailers.
> +By default, a '<token>=<value>' or '<token>:<value>' argument given
> +using `--trailer` will be appended after the existing trailers only if
> +the last trailer has a different (<token>, <value>) pair (or if there
> +is no existing trailer). The <token> and <value> parts will be trimmed
> +to remove starting and trailing whitespace, and the resulting trimmed
> +<token> and <value> will appear in the message like this:
> +token: value
> +This means that the trimmed <token> and <value> will be separated by
> +`': '` (one colon followed by one space).
> +By default the new trailer will appear at the end of all the existing
> +trailers. If there is no existing trailer, the new trailer will appear
> +after the commit message part of the ouput, and, if there is no line
> +with only spaces at the end of the commit message part, one blank line
> +will be added before the new trailer.
> +The trailers are recognized in the input message using the following
> +* by default only lines that contains a ':' (colon) are considered
> + trailers,
> +* the trailer lines must all be next to each other,
> +* after them it's only possible to have some lines that contain only
> + spaces, and then a patch; the patch part is recognized using the
> + fact that its first line starts with '---' (three minus signs),
Is that "starts with" or "consists solely of"?
> +* before them there must be at least one line with only spaces.
I had little bit of trouble parsing those three points, and it seems like a
lot of text to describe something simple. How about a single paragraph:
Existing trailers are extracted from the input message by looking for a group
of one or more lines that contain a colon (by default), where the group is
preceded by one or more empty (or whitespace-only) lines. The group must
either be at the end of the message or be the last non-whitespace lines
before a line that starts with '---' (three minus signs).
Also, will a trailer be recognized if there is whitespace before and/or after
the separator? Can there be whitespace before the token? In the token? (I
don't feel strongly about the answers to these questions, they just came to
mind as I read the documentation.)
> +Note that 'trailers' do not follow and are not intended to follow many
> +rules for RFC 822 headers. For example they do not follow the line
> +folding rules, the encoding rules and probably many other rules.
> + If the <value> part of any trailer contains only whitespace,
> + the whole trailer will be removed from the resulting message.
> + This apply to existing trailers as well as new trailers.
> +--trailer <token>[(=|:)<value>]::
> + Specify a (<token>, <value>) pair that should be applied as a
> + trailer to the input messages. See the description of this
> + command.
> +CONFIGURATION VARIABLES
> + This option tells which characters are recognized as trailer
> + separators. By default only ':' is recognized as a trailer
> + separator, except that '=' is always accepted on the command
> + line for compatibility with other git commands.
> +The first character given by this option will be the default character
> +used when another separator is not specified in the config for this
> +For example, if the value for this option is "%=$", then only lines
> +using the format '<token><sep><value>' with <sep> containing '%', '='
> +or '$' and then spaces will be considered trailers. And '%' will be
> +the default separator used, so by default trailers will appear like:
> +'<token>% <value>' (one percent sign and one space will appear between
> +the token and the value).
> + This option tells where a new trailer will be added.
> +This can be `end`, which is the default, `start`, `after` or `before`.
> +If it is `end`, then each new trailer will appear at the end of the
> +existing trailers.
> +If it is `start`, then each new trailer will appear at the start,
> +instead of the end, of the existing trailers.
> +If it is `after`, then each new trailer will appear just after the
> +last trailer with the same <token>.
> +If it is `before`, then each new trailer will appear just before the
> +last trailer with the same <token>.
It seems to me that it would be more sensible to make the new trailer appear
before the *first* trailer with the same token. Otherwise you can end up
with a somewhat unintuitive order, e.g. if we add values A B C D E (in that
order) we get
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html