From: Junio C Hamano <gits...@pobox.com> > > Christian Couder <chrisc...@tuxfamily.org> writes: > >> +Help add RFC 822-like headers, called 'trailers', at the end of the >> +otherwise free-form part of a commit message. > > I think it is somewhat misleading to use the word "headers" like > that. 'trailers' look similar to RFC-822-headers but they come at > the end. The sentence however reads as if they are "headers" that > look like RFC 822. Perhaps shuffling words like so: > > Help adding 'trailers' lines, that look similar to RFC 822 > e-mail headers, at the end of the ... > > would make it less confusing.
Ok, I made this change in v11. >> +Some configuration variables control the way the `token` arguments are >> +applied to the message and the way any existing trailer in the message >> +is changed. They also make it possible to automatically add some >> +trailers. >> + >> +By default, a 'token=value' or 'token:value' argument will be added >> +only if no trailer with the same (token, value) pair is already in the >> +message. 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 >> +------------------------------------------------ > > Mental note: this does assume that the final output for the 'token' > is to have a line <label> that is followed by a colon ":", SP and > the value. > > And the natural way to express that on the command line would be to > say "token: value", I would think, but let's just read on. > >> +Note that 'trailers' do not follow and are not intended to follow many >> +rules that are in RFC 822. For example they do not follow the line >> +breaking rules, the encoding rules and probably many other rules. > > s/that are in RFC 822/for RFC 822 headers/. > s/line breaking/line folding/. (see RFC 822, 3.1.1) Ok, it's in v11 too. >> +OPTIONS >> +------- >> +--trim-empty:: >> + If the 'value' part of any trailer contains only whitespace, >> + the whole trailer will be removed from the resulting message. >> + >> +CONFIGURATION VARIABLES >> +----------------------- >> + >> +trailer.<token>.key:: >> + This 'key' will be used instead of 'token' in the > > As `key` is something that is typed literally, it should be typeset > as `key` in the descriptive text. Ok, I used `key` in v11. > I think other manpages spell the > placeholder as `<token>` (or '<token>', I am not sure which...). I found mostly <token>, so I used that in v11. >> + trailer. After some alphanumeric characters, it can contain >> + some non alphanumeric characters like ':', '=' or '#' that will >> + be used instead of ':' to separate the token from the value in >> + the trailer, though the default ':' is more standard. > > I assume that this is for things like > > bug #538 > > and the configuration would say something like: > > [trailer "bug"] > key = "bug #" > > For completeness (of this example), the bog-standard s-o-b would > look like > > Signed-off-by: Christian Couder <chrisc...@tuxfamily.org> > > and the configuration for it that spell the redundant "key" would > be: > > [trailer "Signed-off-by"] > key = "Signed-off-by: " Yeah, but you can use the following instead: [trailer "s-o-b"] key = "Signed-off-by: " The <token> and the key can be different. > Am I reading the intention correctly? Yeah, I think so. > That is, when trailer.<token>.key is not defined, the value defaults > to "<token>: " (with one SP after the label and colon), Yes. > and when it > is defined, the value can come directly after it. The value can come directly after the key, only if the key ends with '#'. If it ends with something else, except spaces, one SP will be added between the key and the value. Yeah, I made '#' special in the hope that it would be more compatible with GitHub and other services that might also use '#'. Thanks, 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