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.
> +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)
> +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. I think other manpages spell the
placeholder as `<token>` (or '<token>', I am not sure which...).
> + 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: "
Am I reading the intention correctly?
That is, when trailer.<token>.key is not defined, the value defaults
to "<token>: " (with one SP after the label and colon), and when it
is defined, the value can come directly after it.
--
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