Re: [PATCH v13 11/11] Documentation: add documentation for 'git interpret-trailers'
On 14-08-20 11:39 PM, Christian Couder wrote: 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: + +* 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.) Wouldn't it be more robust to do it the other way? I can imagine cases when a human might want to start a line of text with ---, whereas we can make sure that git tools always use a plain --- line with no extra text. Not a big deal either way though. Thanks for working on this! M. -- 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
Re: [PATCH v13 11/11] Documentation: add documentation for 'git interpret-trailers'
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 chrisc...@tuxfamily.org Signed-off-by: Junio C Hamano gits...@pobox.com --- 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 000..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. ++
Re: [PATCH v13 11/11] Documentation: add documentation for 'git interpret-trailers'
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 'tokensepvalue' 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
