While at it add git-interpret-trailers to "command-list.txt". Signed-off-by: Christian Couder <chriscool@xxxxxxxxxxxxx> Signed-off-by: Junio C Hamano <gitster@xxxxxxxxx> --- Documentation/git-interpret-trailers.txt | 143 +++++++++++++++++++++++++++++++ command-list.txt | 1 + 2 files changed, 144 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..450ec54 --- /dev/null +++ b/Documentation/git-interpret-trailers.txt @@ -0,0 +1,143 @@ +git-interpret-trailers(1) +========================= + +NAME +---- +git-interpret-trailers - help add stuctured information into commit messages + +SYNOPSIS +-------- +[verse] +'git interpret-trailers' [--trim-empty] [(--trailer <token>[(=|:)<value>])...] [<file>...] + +DESCRIPTION +----------- +Help adding 'trailers' lines, that look similar to RFC 822 e-mail +headers, at the end of the otherwise free-form part of a commit +message. + +This command reads some patches or commit messages from either the +<file> arguments or the standard input if no <file> is specified. Then +this command applies the arguments passed using the `--trailer` +option, if any, to the commit message part of each input file. The +result is emitted on the standard output. + +Some configuration variables control the way the `--trailer` arguments +are applied to each commit message and the way any existing trailer in +the commit message is changed. They also make it possible to +automatically add some trailers. + +By default, a '<token>=<value>' or '<token>:<value>' argument given +using `--trailer` 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. + +The trailers are recognized in the input commit message using the +following rules: + +* only lines that contains a ':' are considered trailers, +* the trailer lines must all be next to each other, +* after them it's only possible to have some lines that contain only spaces, +* before them there must be at least one line with only spaces. + +Note that 'trailers' do not follow and are not intended to follow many +rules for RFC 822 headers. For example they do not follow the line +folding 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. + This apply to existing trailers as well as new trailers. + +--trailer <token>[(=|:)<value>]:: + Specify a (<token>, <value>) pair that should be applied as a + trailer to the input messages. See the description of this + command. + +CONFIGURATION VARIABLES +----------------------- + +trailer.<token>.key:: + This `key` will be used instead of <token> in the + trailer. After the last alphanumeric character, 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, the behavior is as if a special +'<token>=<value>' argument were added at the end of the command line, +where <value> is taken to be the standard output of the specified +command with any leading and trailing whitespace trimmed off. ++ +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 diff --git a/command-list.txt b/command-list.txt index cf36c3d..d5e0bed 100644 --- a/command-list.txt +++ b/command-list.txt @@ -62,6 +62,7 @@ git-imap-send foreignscminterface git-index-pack plumbingmanipulators git-init mainporcelain common git-instaweb ancillaryinterrogators +git-interpret-trailers purehelpers gitk mainporcelain git-log mainporcelain common git-ls-files plumbinginterrogators -- 1.9.1.636.g20d5f34 -- 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