diff --git a/Documentation/config/trailer.adoc b/Documentation/config/trailer.adoc index 60bc221c88..1bc70192d3 100644 --- a/Documentation/config/trailer.adoc +++ b/Documentation/config/trailer.adoc @@ -1,21 +1,21 @@ -trailer.separators:: +`trailer.separators`:: This option tells which characters are recognized as trailer - separators. By default only ':' is recognized as a trailer - separator, except that '=' is always accepted on the command + separators. By default only `:` is recognized as a trailer + separator, except that `=` is always accepted on the command line for compatibility with other git commands. + The first character given by this option will be the default character used when another separator is not specified in the config for this trailer. + -For example, if the value for this option is "%=$", then only lines -using the format '' with containing '%', '=' -or '$' and then spaces will be considered trailers. And '%' will be +For example, if the value for this option is `%=$`, then only lines +using the format __ with __ containing `%`, `=` +or `$` and then spaces will be considered trailers. And `%` will be the default separator used, so by default trailers will appear like: -'% ' (one percent sign and one space will appear between +`% ` (one percent sign and one space will appear between the key and the value). -trailer.where:: +`trailer.where`:: This option tells where a new trailer will be added. + This can be `end`, which is the default, `start`, `after` or `before`. @@ -27,41 +27,41 @@ If it is `start`, then each new trailer will appear at the start, instead of the end, of the existing trailers. + If it is `after`, then each new trailer will appear just after the -last trailer with the same . +last trailer with the same __. + If it is `before`, then each new trailer will appear just before the -first trailer with the same . +first trailer with the same __. -trailer.ifexists:: +`trailer.ifexists`:: This option makes it possible to choose what action will be performed when there is already at least one trailer with the - same in the input. + same __ in the input. + The valid values for this option are: `addIfDifferentNeighbor` (this is the default), `addIfDifferent`, `add`, `replace` or `doNothing`. + With `addIfDifferentNeighbor`, a new trailer will be added only if no -trailer with the same (, ) pair is above or below the line +trailer with the same (__, __) pair is above or below the line where the new trailer will be added. + With `addIfDifferent`, a new trailer will be added only if no trailer -with the same (, ) pair is already in the input. +with the same (__, __) pair is already in the input. + With `add`, a new trailer will be added, even if some trailers with -the same (, ) pair are already in the input. +the same (__, __) pair are already in the input. + -With `replace`, an existing trailer with the same will be +With `replace`, an existing trailer with the same __ will be deleted and the new trailer will be added. The deleted trailer will be -the closest one (with the same ) to the place where the new one +the closest one (with the same __) to the place where the new one will be added. + With `doNothing`, nothing will be done; that is no new trailer will be -added if there is already one with the same in the input. +added if there is already one with the same __ in the input. -trailer.ifmissing:: +`trailer.ifmissing`:: This option makes it possible to choose what action will be performed when there is not yet any trailer with the same - in the input. + __ in the input. + The valid values for this option are: `add` (this is the default) and `doNothing`. @@ -70,67 +70,68 @@ With `add`, a new trailer will be added. + With `doNothing`, nothing will be done. -trailer..key:: - Defines a for the . The must be a - prefix (case does not matter) of the . For example, in `git - config trailer.ack.key "Acked-by"` the "Acked-by" is the and - the "ack" is the . This configuration allows the shorter +`trailer..key`:: + Defines a __ for the __. The __ must be a + prefix (case does not matter) of the __. For example, in `git + config trailer.ack.key "Acked-by"` the `Acked-by` is the __ and + the `ack` is the __. This configuration allows the shorter `--trailer "ack:..."` invocation on the command line using the "ack" - instead of the longer `--trailer "Acked-by:..."`. + `` instead of the longer `--trailer "Acked-by:..."`. + -At the end of the , a separator can appear and then some -space characters. By default the only valid separator is ':', +At the end of the __, a separator can appear and then some +space characters. By default the only valid separator is `:`, but this can be changed using the `trailer.separators` config variable. + If there is a separator in the key, then it overrides the default separator when adding the trailer. -trailer..where:: - This option takes the same values as the 'trailer.where' +`trailer..where`:: + This option takes the same values as the `trailer.where` configuration variable and it overrides what is specified by - that option for trailers with the specified . + that option for trailers with the specified __. -trailer..ifexists:: - This option takes the same values as the 'trailer.ifexists' +`trailer..ifexists`:: + This option takes the same values as the `trailer.ifexists` configuration variable and it overrides what is specified by - that option for trailers with the specified . + that option for trailers with the specified __. -trailer..ifmissing:: - This option takes the same values as the 'trailer.ifmissing' +`trailer..ifmissing`:: + This option takes the same values as the `trailer.ifmissing` configuration variable and it overrides what is specified by - that option for trailers with the specified . + that option for trailers with the specified __. -trailer..command:: - Deprecated in favor of 'trailer..cmd'. - This option behaves in the same way as 'trailer..cmd', except +`trailer..command`:: + Deprecated in favor of `trailer..cmd`. + This option behaves in the same way as `trailer..cmd`, except that it doesn't pass anything as argument to the specified command. - Instead the first occurrence of substring $ARG is replaced by the - that would be passed as argument. + Instead the first occurrence of substring `$ARG` is replaced by the + __ that would be passed as argument. + -Note that $ARG in the user's command is -only replaced once and that the original way of replacing $ARG is not safe. +Note that `$ARG` in the user's command is +only replaced once and that the original way of replacing `$ARG` is not safe. + -When both 'trailer..cmd' and 'trailer..command' are given -for the same , 'trailer..cmd' is used and -'trailer..command' is ignored. +When both `trailer..cmd` and `trailer..command` are given +for the same __, `trailer..cmd` is used and +`trailer..command` is ignored. -trailer..cmd:: +`trailer..cmd`:: This option can be used to specify a shell command that will be called - once to automatically add a trailer with the specified , and then - called each time a '--trailer =' argument is specified to - modify the of the trailer that this option would produce. + once to automatically add a trailer with the specified __, and then + called each time a `--trailer =` argument is specified to + modify the __ of the trailer that this option would produce. + When the specified command is first called to add a trailer -with the specified , the behavior is as if a special -'--trailer =' argument was added at the beginning -of the "git interpret-trailers" command, where -is taken to be the standard output of the command with any -leading and trailing whitespace trimmed off. +with the specified __, the behavior is as if a special +`--trailer =` argument was added at the beginning +of linkgit:git-interpret-trailers[1], where __ is taken to be the +standard output of the command with any leading and trailing whitespace +trimmed off. + -If some '--trailer =' arguments are also passed +If some `--trailer =` arguments are also passed on the command line, the command is called again once for each -of these arguments with the same . And the part +of these arguments with the same __. And the __ part of these arguments, if any, will be passed to the command as its -first argument. This way the command can produce a computed -from the passed in the '--trailer =' argument. +first argument. This way the command can produce a __ computed +from the __ passed in the `--trailer =` +argument. diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc index fd335fe772..77b4f63b05 100644 --- a/Documentation/git-interpret-trailers.adoc +++ b/Documentation/git-interpret-trailers.adoc @@ -7,14 +7,14 @@ git-interpret-trailers - Add or parse structured information in commit messages SYNOPSIS -------- -[verse] -'git interpret-trailers' [--in-place] [--trim-empty] +[synopsis] +git interpret-trailers [--in-place] [--trim-empty] [(--trailer (|)[(=|:)])...] [--parse] [...] DESCRIPTION ----------- -Add or parse 'trailer' lines that look similar to RFC 822 e-mail +Add or parse _trailer_ lines that look similar to RFC 822 e-mail headers, at the end of the otherwise free-form part of a commit message. For example, in the following commit message @@ -27,23 +27,24 @@ Signed-off-by: Alice Signed-off-by: Bob ------------------------------------------------ -the last two lines starting with "Signed-off-by" are trailers. +the last two lines starting with `Signed-off-by` are trailers. This command reads commit messages from either the - arguments or the standard input if no is specified. +__ arguments or the standard input if no __ is specified. If `--parse` is specified, the output consists of the parsed trailers coming from the input, without influencing them with any command line options or configuration variables. -Otherwise, this command applies `trailer.*` configuration variables -(which could potentially add new trailers, as well as reposition them), -as well as any command line arguments that can override configuration -variables (such as `--trailer=...` which could also add new trailers), -to each input file. The result is emitted on the standard output. +Otherwise, this command applies `trailer.` configuration +variables (which could potentially add new trailers, as well as +reposition them), as well as any command line arguments that can +override configuration variables (such as `--trailer=...` which could +also add new trailers), to each input file. The result is emitted on the +standard output. This command can also operate on the output of linkgit:git-format-patch[1], which is more elaborate than a plain commit message. Namely, such output -includes a commit message (as above), a "---" divider line, and a patch part. +includes a commit message (as above), a `---` divider line, and a patch part. For these inputs, the divider and patch parts are not modified by this command and are emitted as is on the output, unless `--no-divider` is specified. @@ -53,24 +54,24 @@ are applied to each input and the way any existing trailer in the input is changed. They also make it possible to automatically add some trailers. -By default, a '=' or ':' argument given +By default, a `=` or `:` argument given using `--trailer` will be appended after the existing trailers only if -the last trailer has a different (, ) pair (or if there -is no existing trailer). The and parts will be trimmed +the last trailer has a different (__, __) pair (or if there +is no existing trailer). The __ and __ parts will be trimmed to remove starting and trailing whitespace, and the resulting trimmed - and will appear in the output like this: +__ and __ will appear in the output like this: ------------------------------------------------ key: value ------------------------------------------------ -This means that the trimmed and will be separated by -`': '` (one colon followed by one space). +This means that the trimmed __ and __ will be separated by +"`:`{nbsp}" (one colon followed by one space). -For convenience, a can be configured to make using `--trailer` +For convenience, a __ can be configured to make using `--trailer` shorter to type on the command line. This can be configured using the -'trailer..key' configuration variable. The must be a prefix -of the full string, although case sensitivity does not matter. For +`trailer..key` configuration variable. The __ must be a prefix +of the full __ string, although case sensitivity does not matter. For example, if you have ------------------------------------------------ @@ -91,13 +92,13 @@ least one Git-generated or user-configured trailer and consists of at least 25% trailers. The group must be preceded by one or more empty (or whitespace-only) lines. The group must either be at the end of the input or be the last -non-whitespace lines before a line that starts with '---' (followed by a +non-whitespace lines before a line that starts with `---` (followed by a space or the end of the line). When reading trailers, there can be no whitespace before or inside the -, but any number of regular space and tab characters are allowed -between the and the separator. There can be whitespaces before, -inside or after the . The may be split over multiple lines +__, but any number of regular space and tab characters are allowed +between the __ and the separator. There can be whitespaces before, +inside or after the __. The __ may be split over multiple lines with each subsequent line starting with at least one whitespace, like the "folding" in RFC 822. Example: @@ -111,77 +112,97 @@ rules for RFC 822 headers. For example they do not follow the encoding rule. OPTIONS ------- ---in-place:: - Edit the files in place. +`--in-place`:: +`--no-in-place`:: + Edit the files in place. The default is `--no-in-place`. ---trim-empty:: - If the part of any trailer contains only whitespace, +`--trim-empty`:: +`--no-trim-empty`:: + If the __ part of any trailer contains only whitespace, the whole trailer will be removed from the output. This applies to existing trailers as well as new trailers. ++ +The default is `--no-trim-empty`. ---trailer [(=|:)]:: - Specify a (, ) pair that should be applied as a - trailer to the inputs. See the description of this - command. +`--trailer=[(=|:)]`:: +`--no-trailer`:: + Specify a (__, __) pair that should be applied as a + trailer to the inputs. See the description of this command. Can + be given multiple times. ++ +Use `--no-trailer` to reset the list. ---where :: ---no-where:: +`--where=`:: +`--no-where`:: Specify where all new trailers will be added. A setting - provided with '--where' overrides the `trailer.where` and any - applicable `trailer..where` configuration variables - and applies to all '--trailer' options until the next occurrence of - '--where' or '--no-where'. Upon encountering '--no-where', clear the - effect of any previous use of '--where', such that the relevant configuration - variables are no longer overridden. Possible placements are `after`, + provided with `--where` overrides the `trailer.where` and any + applicable `trailer..where` configuration variables + and applies to all `--trailer` options until the next occurrence of + `--where` or `--no-where`. Possible placements are `after`, `before`, `end` or `start`. ++ +Use `--no-where` to clear the effect of any previous use of `--where`, +such that the relevant configuration variables are no longer overridden. ---if-exists :: ---no-if-exists:: +`--if-exists=`:: +`--no-if-exists`:: Specify what action will be performed when there is already at - least one trailer with the same in the input. A setting - provided with '--if-exists' overrides the `trailer.ifExists` and any - applicable `trailer..ifExists` configuration variables - and applies to all '--trailer' options until the next occurrence of - '--if-exists' or '--no-if-exists'. Upon encountering '--no-if-exists', clear the - effect of any previous use of '--if-exists', such that the relevant configuration - variables are no longer overridden. Possible actions are `addIfDifferent`, + least one trailer with the same __ in the input. A setting + provided with `--if-exists` overrides the `trailer.ifExists` and any + applicable `trailer..ifExists` configuration variables + and applies to all `--trailer` options until the next occurrence of + `--if-exists` or `--no-if-exists`. Possible actions are `addIfDifferent`, `addIfDifferentNeighbor`, `add`, `replace` and `doNothing`. ++ +Use `--no-if-exists` to clear the effect of any previous use of +`--if-exists`, such that the relevant configuration variables are no +longer overridden. ---if-missing :: ---no-if-missing:: +`--if-missing=`:: +`--no-if-missing`:: Specify what action will be performed when there is no other - trailer with the same in the input. A setting - provided with '--if-missing' overrides the `trailer.ifMissing` and any - applicable `trailer..ifMissing` configuration variables - and applies to all '--trailer' options until the next occurrence of - '--if-missing' or '--no-if-missing'. Upon encountering '--no-if-missing', - clear the effect of any previous use of '--if-missing', such that the relevant - configuration variables are no longer overridden. Possible actions are `doNothing` - or `add`. + trailer with the same __ in the input. A setting + provided with `--if-missing` overrides the `trailer.ifMissing` and any + applicable `trailer..ifMissing` configuration variables + and applies to all `--trailer` options until the next occurrence of + `--if-missing` or `--no-if-missing`. Possible actions are + `doNothing` or `add`. ++ +Use `--no-if-missing` to clear the effect of any previous use of +`--if-missing`, such that the relevant configuration variables are no +longer overridden. ---only-trailers:: - Output only the trailers, not any other parts of the input. +`--only-trailers`:: +`--no-only-trailers`:: + Output only the trailers, not any other parts of the + input. The default is `--no-only-trailers`. ---only-input:: +`--only-input`:: +`--no-only-input`:: Output only trailers that exist in the input; do not add any - from the command-line or by applying `trailer.*` configuration - variables. + from the command-line or by applying `trailer.` configuration + variables. The default is `--no-only-input`. ---unfold:: +`--unfold`:: +`--no-unfold`:: If a trailer has a value that runs over multiple lines (aka "folded"), - reformat the value into a single line. + reformat the value into a single line. The default is `--no-unfold`. ---parse:: +`--parse`:: A convenience alias for `--only-trailers --only-input --unfold`. This makes it easier to only see the trailers coming from the input without influencing them with any command line options or configuration variables, while also making the output machine-friendly with - --unfold. + `--unfold`. ++ +There is no convenience alias to negate this alias. ---no-divider:: - Do not treat `---` as the end of the commit message. Use this - when you know your input contains just the commit message itself - (and not an email or the output of `git format-patch`). +`--divider`:: +`--no-divider`:: + Treat `---` as the end of the commit message. This is the default. + Use `--no-divider` when you know your input contains just the + commit message itself (and not an email or the output of + linkgit:git-format-patch[1]). CONFIGURATION VARIABLES ----------------------- @@ -193,7 +214,7 @@ include::config/trailer.adoc[] EXAMPLES -------- -* Configure a 'sign' trailer with a 'Signed-off-by' key, and then +* Configure a `sign` trailer with a `Signed-off-by` key, and then add two of these trailers to a commit message file: + ------------ @@ -230,8 +251,8 @@ Signed-off-by: Bob Acked-by: Alice ------------ -* Extract the last commit as a patch, and add a 'Cc' and a - 'Reviewed-by' trailer to it: +* Extract the last commit as a patch, and add a `Cc` and a + `Reviewed-by` trailer to it: + ------------ $ git format-patch -1 @@ -239,9 +260,9 @@ $ git format-patch -1 $ git interpret-trailers --trailer 'Cc: Alice ' --trailer 'Reviewed-by: Bob ' 0001-foo.patch >0001-bar.patch ------------ -* Configure a 'sign' trailer with a command to automatically add a - 'Signed-off-by: ' with the author information only if there is no - 'Signed-off-by: ' already, and show how it works: +* Configure a `sign` trailer with a command to automatically add a + "`Signed-off-by:`{nbsp}" with the author information only if there is no + "`Signed-off-by:`{nbsp}" already, and show how it works: + ------------ $ cat msg1.txt @@ -272,7 +293,7 @@ body text Signed-off-by: Alice ------------ -* Configure a 'fix' trailer with a key that contains a '#' and no +* Configure a `fix` trailer with a key that contains a `#` and no space after this character, and show how it works: + ------------ @@ -284,7 +305,7 @@ subject Fix #42 ------------ -* Configure a 'help' trailer with a cmd use a script `glog-find-author` +* Configure a `help` trailer with a cmd use a script `glog-find-author` which search specified author identity from git log in git repository and show how it works: + @@ -308,7 +329,7 @@ Helped-by: Junio C Hamano Helped-by: Christian Couder ------------ -* Configure a 'ref' trailer with a cmd use a script `glog-grep` +* Configure a `ref` trailer with a cmd use a script `glog-grep` to grep last relevant commit from git log in the git repository and show how it works: + @@ -331,7 +352,7 @@ body text Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07) ------------ -* Configure a 'see' trailer with a command to show the subject of a +* Configure a `see` trailer with a command to show the subject of a commit that is related, and show how it works: + ------------ @@ -359,8 +380,8 @@ See-also: fe3187489d69c4 (subject of related commit) * Configure a commit template with some trailers with empty values (using sed to show and keep the trailing spaces at the end of the trailers), then configure a commit-msg hook that uses - 'git interpret-trailers' to remove trailers with empty values and - to add a 'git-version' trailer: + git-interpret-trailers(1) to remove trailers with empty values and to + add a `git-version` trailer: + ------------ $ cat temp.txt diff --git a/builtin/interpret-trailers.c b/builtin/interpret-trailers.c index acaf42b2d9..e7e86e9523 100644 --- a/builtin/interpret-trailers.c +++ b/builtin/interpret-trailers.c @@ -156,7 +156,7 @@ int cmd_interpret_trailers(int argc, N_("action if trailer is missing"), option_parse_if_missing), OPT_BOOL(0, "only-trailers", &opts.only_trailers, N_("output only the trailers")), - OPT_BOOL(0, "only-input", &opts.only_input, N_("do not apply trailer.* configuration variables")), + OPT_BOOL(0, "only-input", &opts.only_input, N_("do not apply trailer. configuration variables")), OPT_BOOL(0, "unfold", &opts.unfold, N_("reformat multiline trailer values as single-line values")), OPT_CALLBACK_F(0, "parse", &opts, NULL, N_("alias for --only-trailers --only-input --unfold"), PARSE_OPT_NOARG | PARSE_OPT_NONEG, parse_opt_parse),