Re: [PATCH v13 11/11] Documentation: add documentation for 'git interpret-trailers'
From: Marc Branchaud <hidden>
Date: 2016-06-15 23:02:19
On 14-08-16 12:06 PM, Christian Couder wrote:
quoted hunk ↗ jump to hunk
While at it add git-interpret-trailers to "command-list.txt". Signed-off-by: Christian Couder <redacted> Signed-off-by: Junio C Hamano <redacted> --- Documentation/git-interpret-trailers.txt | 308 +++++++++++++++++++++++++++++++ command-list.txt | 1 + 2 files changed, 309 insertions(+) create mode 100644 Documentation/git-interpret-trailers.txtdiff --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.