From: Junio C Hamano <gitster@pobox.com>
To: Christian Couder <chriscool@tuxfamily.org>
Cc: git@vger.kernel.org, Johan Herland <johan@herland.net>,
Josh Triplett <josh@joshtriplett.org>,
Thomas Rast <tr@thomasrast.ch>,
Michael Haggerty <mhagger@alum.mit.edu>,
Dan Carpenter <dan.carpenter@oracle.com>,
Greg Kroah-Hartman <greg@kroah.com>, Jeff King <peff@peff.net>,
Eric Sunshine <sunshine@sunshineco.com>,
Ramsay Jones <ramsay@ramsay1.demon.co.uk>,
Jonathan Nieder <jrnieder@gmail.com>
Subject: Re: [PATCH v10 11/12] Documentation: add documentation for 'git interpret-trailers'
Date: Tue, 08 Apr 2014 14:26:40 -0700 [thread overview]
Message-ID: <xmqqmwfv3433.fsf@gitster.dls.corp.google.com> (raw)
In-Reply-To: <20140406170204.15116.15559.chriscool@tuxfamily.org> (Christian Couder's message of "Sun, 06 Apr 2014 19:02:02 +0200")
Christian Couder <chriscool@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.
> +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@tuxfamily.org>
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.
next prev parent reply other threads:[~2014-04-08 21:26 UTC|newest]
Thread overview: 33+ messages / expand[flat|nested] mbox.gz Atom feed top
2014-04-06 17:01 [PATCH v10 00/12] Add interpret-trailers builtin Christian Couder
2014-04-06 17:01 ` [PATCH v10 01/12] trailer: add data structures and basic functions Christian Couder
2014-04-06 17:01 ` [PATCH v10 02/12] trailer: process trailers from stdin and arguments Christian Couder
2014-04-06 17:01 ` [PATCH v10 03/12] trailer: read and process config information Christian Couder
2014-04-06 17:01 ` [PATCH v10 04/12] trailer: process command line trailer arguments Christian Couder
2014-04-06 17:01 ` [PATCH v10 05/12] trailer: parse trailers from stdin Christian Couder
2014-04-06 17:01 ` [PATCH v10 06/12] trailer: put all the processing together and print Christian Couder
2014-04-06 17:01 ` [PATCH v10 07/12] trailer: add interpret-trailers command Christian Couder
2014-04-06 17:01 ` [PATCH v10 08/12] trailer: add tests for "git interpret-trailers" Christian Couder
2014-04-06 17:02 ` [PATCH v10 09/12] trailer: execute command from 'trailer.<name>.command' Christian Couder
2014-04-06 17:02 ` [PATCH v10 10/12] trailer: add tests for commands in config file Christian Couder
2014-04-06 17:02 ` [PATCH v10 11/12] Documentation: add documentation for 'git interpret-trailers' Christian Couder
2014-04-08 7:30 ` Michael Haggerty
2014-04-08 11:35 ` Christian Couder
2014-04-08 15:25 ` Michael Haggerty
2014-04-25 21:07 ` Christian Couder
2014-04-28 10:16 ` Michael Haggerty
2014-05-25 8:37 ` Christian Couder
2014-05-27 8:21 ` Michael Haggerty
2014-05-27 9:17 ` Johan Herland
2014-05-27 19:18 ` Junio C Hamano
2014-04-08 16:52 ` Junio C Hamano
2014-04-08 21:26 ` Junio C Hamano [this message]
2014-04-25 19:56 ` Christian Couder
2014-04-28 16:37 ` Junio C Hamano
2014-04-29 11:05 ` Jeremy Morton
2014-04-29 11:47 ` Christian Couder
2014-04-29 13:25 ` Jeremy Morton
2014-05-01 18:54 ` Christian Couder
2014-04-29 13:25 ` Jeremy Morton
2014-04-06 17:02 ` [PATCH v10 12/12] trailer: add blank line before the trailers if needed Christian Couder
2014-04-07 21:38 ` Junio C Hamano
2014-04-08 12:48 ` Christian Couder
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=xmqqmwfv3433.fsf@gitster.dls.corp.google.com \
--to=gitster@pobox.com \
--cc=chriscool@tuxfamily.org \
--cc=dan.carpenter@oracle.com \
--cc=git@vger.kernel.org \
--cc=greg@kroah.com \
--cc=johan@herland.net \
--cc=josh@joshtriplett.org \
--cc=jrnieder@gmail.com \
--cc=mhagger@alum.mit.edu \
--cc=peff@peff.net \
--cc=ramsay@ramsay1.demon.co.uk \
--cc=sunshine@sunshineco.com \
--cc=tr@thomasrast.ch \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).