On Thu, Aug 21, 2014 at 12:05 AM, Marc Branchaud <marcn...@xiplink.com> wrote: > On 14-08-16 12:06 PM, Christian Couder wrote: > >> +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. >> + 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.) >> + >> +* 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. >> +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. -- 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
