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 <chriscool@xxxxxxxxxxxxx> > Signed-off-by: Junio C Hamano <gitster@xxxxxxxxx> > --- > 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 b/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(1) > +========================= > + > +NAME > +---- > +git-interpret-trailers - help add stuctured information into commit messages > + > +SYNOPSIS > +-------- > +[verse] > +'git interpret-trailers' [--trim-empty] [(--trailer <token>[(=|:)<value>])...] [<file>...] > + > +DESCRIPTION > +----------- > +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 > +message. > + > +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 > +rules: > + > +* by default only lines that contains a ':' (colon) are considered s/contains/contain/ > + 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. > + > +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. 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 foo: B foo: C foo: D foo: E foo: A M. -- 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