From: Junio C Hamano <gitster@xxxxxxxxx>
>
> Christian Couder <chriscool@xxxxxxxxxxxxx> 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 <chriscool@xxxxxxxxxxxxx>
>
> 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 majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html