From: Marc Branchaud Date: Wed, 20 Aug 2014 22:05:12 GMT Subject: Re: [PATCH v13 11/11] Documentation: add documentation for 'git interpret-trailers' Message-ID: <53F51B98.2060903@xiplink.com> In-Reply-To: <20140816160622.18221.71416.chriscool@tuxfamily.org> 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 > Signed-off-by: Junio C Hamano > --- > 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 [(=|:)])...] [...] > + > +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 > + arguments or the standard input if no 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 '=' or ':' argument given > +using `--trailer` will be appended after the existing trailers only if > +the last trailer has a different (, ) pair (or if there > +is no existing trailer). The and parts will be trimmed > +to remove starting and trailing whitespace, and the resulting trimmed > + and will appear in the message like this: > + > +------------------------------------------------ > +token: value > +------------------------------------------------ > + > +This means that the trimmed and 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 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 [(=|:)]:: > + Specify a (, ) 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 '' with containing '%', '=' > +or '$' and then spaces will be considered trailers. And '%' will be > +the default separator used, so by default trailers will appear like: > +'% ' (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 . > ++ > +If it is `before`, then each new trailer will appear just before the > +last trailer with the same . 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.