From: Christian Couder <chriscool@tuxfamily.org>
To: Junio C Hamano <gitster@pobox.com>
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: [PATCH v10 11/12] Documentation: add documentation for 'git interpret-trailers'
Date: Sun, 06 Apr 2014 19:02:02 +0200 [thread overview]
Message-ID: <20140406170204.15116.15559.chriscool@tuxfamily.org> (raw)
In-Reply-To: <20140406163214.15116.91484.chriscool@tuxfamily.org>
Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
Documentation/git-interpret-trailers.txt | 123 +++++++++++++++++++++++++++++++
1 file changed, 123 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 0000000..75ae386
--- /dev/null
+++ b/Documentation/git-interpret-trailers.txt
@@ -0,0 +1,123 @@
+git-interpret-trailers(1)
+=========================
+
+NAME
+----
+git-interpret-trailers - help add stuctured information into commit messages
+
+SYNOPSIS
+--------
+[verse]
+'git interpret-trailers' [--trim-empty] [(<token>[(=|:)<value>])...]
+
+DESCRIPTION
+-----------
+Help add RFC 822-like headers, called 'trailers', at the end of the
+otherwise free-form part of a commit message.
+
+This command is a filter. It reads the standard input for a commit
+message and applies the `token` arguments, if any, to this
+message. The resulting message is emited on the standard output.
+
+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
+------------------------------------------------
+
+By default, if there are already trailers with the same 'token', the
+new trailer will appear just after the last trailer with the same
+'token'. Otherwise it will appear at the end of the message.
+
+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.
+
+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
+ 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.
+
+trailer.<token>.where::
+ This can be either `after`, which is the default, or
+ `before`. If it is `before`, then a trailer with the specified
+ token, will appear before, instead of after, other trailers
+ with the same token, or otherwise at the beginning, instead of
+ at the end, of all the trailers.
+
+trailer.<token>.ifexist::
+ This option makes it possible to choose what action will be
+ performed when there is already at least one trailer with the
+ same token in the message.
++
+The valid values for this option are: `addIfDifferent` (this is the
+default), `addIfDifferentNeighbor`, `add`, `overwrite` or `doNothing`.
++
+With `addIfDifferent`, a new trailer will be added only if no trailer
+with the same (token, value) pair is already in the message.
++
+With `addIfDifferentNeighbor`, a new trailer will be added only if no
+trailer with the same (token, value) pair is above or below the line
+where the new trailer will be added.
++
+With `add`, a new trailer will be added, even if some trailers with
+the same (token, value) pair are already in the message.
++
+With `overwrite`, the new trailer will overwrite an existing trailer
+with the same token.
++
+With `doNothing`, nothing will be done, that is no new trailer will be
+added if there is already one with the same token in the message.
+
+trailer.<token>.ifmissing::
+ This option makes it possible to choose what action will be
+ performed when there is not yet any trailer with the same
+ token in the message.
++
+The valid values for this option are: `add` (this is the default) and
+`doNothing`.
++
+With `add`, a new trailer will be added.
++
+With `doNothing`, nothing will be done.
+
+trailer.<token>.command::
+ This option can be used to specify a shell command that will
+ be used to automatically add or modify a trailer with the
+ specified 'token'.
++
+When this option is specified, it is like if a special 'token=value'
+argument is added at the end of the command line, where 'value' will
+be given by the standard output of the specified command.
++
+If the command contains the `$ARG` string, this string will be
+replaced with the 'value' part of an existing trailer with the same
+token, if any, before the command is launched.
+
+SEE ALSO
+--------
+linkgit:git-commit[1]
+
+GIT
+---
+Part of the linkgit:git[1] suite
--
1.9.0.163.g8ca203c
next prev parent reply other threads:[~2014-04-07 18:44 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 ` Christian Couder [this message]
2014-04-08 7:30 ` [PATCH v10 11/12] Documentation: add documentation for 'git interpret-trailers' 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
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
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20140406170204.15116.15559.chriscool@tuxfamily.org \
--to=chriscool@tuxfamily.org \
--cc=dan.carpenter@oracle.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--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.
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 NNTP newsgroup(s).