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

On Thu, Aug 21, 2014 at 12:05 AM, Marc Branchaud [off-list ref] wrote:

On 14-08-16 12:06 PM, Christian Couder wrote:

quoted

+The trailers are recognized in the input message using the following
+rules:
+
+* by default only lines that contains a ':' (colon) are considered

s/contains/contain/

Ok.

quoted

+  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"?

It is starts with. (The starts_with() function is used.)

quoted

+
+* 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).

Ok, I will use something like that, thanks.

Also, will a trailer be recognized if there is whitespace before and/or after
the separator?

Yes.

Can there be whitespace before the token?

Yes.

 In the token?

Yes.

(I don't feel strongly about the answers to these questions, they just came to
mind as I read the documentation.)

Ok, I will add something.

quoted

+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.
+
+OPTIONS
+-------
+--trim-empty::
+     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
+-----------------------
+
+trailer.separators::
+     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
+trailer.
++
+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).
+
+trailer.where::
+     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.

Yeah, it is a copy-paste mistake that I will fix.

Thanks for the careful review,
Christian.