diff options
| -rw-r--r-- | Documentation/config/trailer.adoc | 121 |
1 files changed, 61 insertions, 60 deletions
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 '<key><sep><value>' with <sep> 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 _<key><sep><value>_ with _<sep>_ containing `%`, `=` +or `$` and then spaces will be considered trailers. And `%` will be the default separator used, so by default trailers will appear like: -'<key>% <value>' (one percent sign and one space will appear between +`<key>% <value>` (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 <key>. +last trailer with the same _<key>_. + If it is `before`, then each new trailer will appear just before the -first trailer with the same <key>. +first trailer with the same _<key>_. -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 <key> in the input. + same _<key>_ 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 (<key>, <value>) pair is above or below the line +trailer with the same (_<key>_, _<value>_) 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 (<key>, <value>) pair is already in the input. +with the same (_<key>_, _<value>_) pair is already in the input. + With `add`, a new trailer will be added, even if some trailers with -the same (<key>, <value>) pair are already in the input. +the same (_<key>_, _<value>_) pair are already in the input. + -With `replace`, an existing trailer with the same <key> will be +With `replace`, an existing trailer with the same _<key>_ will be deleted and the new trailer will be added. The deleted trailer will be -the closest one (with the same <key>) to the place where the new one +the closest one (with the same _<key>_) 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 <key> in the input. +added if there is already one with the same _<key>_ 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 - <key> in the input. + _<key>_ 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.<keyAlias>.key:: - Defines a <keyAlias> for the <key>. The <keyAlias> must be a - prefix (case does not matter) of the <key>. For example, in `git - config trailer.ack.key "Acked-by"` the "Acked-by" is the <key> and - the "ack" is the <keyAlias>. This configuration allows the shorter +`trailer.<key-alias>.key`:: + Defines a _<key-alias>_ for the _<key>_. The _<key-alias>_ must be a + prefix (case does not matter) of the _<key>_. For example, in `git + config trailer.ack.key "Acked-by"` the `Acked-by` is the _<key>_ and + the `ack` is the _<key-alias>_. This configuration allows the shorter `--trailer "ack:..."` invocation on the command line using the "ack" - <keyAlias> instead of the longer `--trailer "Acked-by:..."`. + `<key-alias>` instead of the longer `--trailer "Acked-by:..."`. + -At the end of the <key>, a separator can appear and then some -space characters. By default the only valid separator is ':', +At the end of the _<key>_, 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.<keyAlias>.where:: - This option takes the same values as the 'trailer.where' +`trailer.<key-alias>.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 <keyAlias>. + that option for trailers with the specified _<key-alias>_. -trailer.<keyAlias>.ifexists:: - This option takes the same values as the 'trailer.ifexists' +`trailer.<key-alias>.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 <keyAlias>. + that option for trailers with the specified _<key-alias>_. -trailer.<keyAlias>.ifmissing:: - This option takes the same values as the 'trailer.ifmissing' +`trailer.<key-alias>.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 <keyAlias>. + that option for trailers with the specified _<key-alias>_. -trailer.<keyAlias>.command:: - Deprecated in favor of 'trailer.<keyAlias>.cmd'. - This option behaves in the same way as 'trailer.<keyAlias>.cmd', except +`trailer.<key-alias>.command`:: + Deprecated in favor of `trailer.<key-alias>.cmd`. + This option behaves in the same way as `trailer.<key-alias>.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 - <value> that would be passed as argument. + Instead the first occurrence of substring `$ARG` is replaced by the + _<value>_ 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.<keyAlias>.cmd' and 'trailer.<keyAlias>.command' are given -for the same <keyAlias>, 'trailer.<keyAlias>.cmd' is used and -'trailer.<keyAlias>.command' is ignored. +When both `trailer.<key-alias>.cmd` and `trailer.<key-alias>.command` are given +for the same _<key-alias>_, `trailer.<key-alias>.cmd` is used and +`trailer.<key-alias>.command` is ignored. -trailer.<keyAlias>.cmd:: +`trailer.<key-alias>.cmd`:: This option can be used to specify a shell command that will be called - once to automatically add a trailer with the specified <keyAlias>, and then - called each time a '--trailer <keyAlias>=<value>' argument is specified to - modify the <value> of the trailer that this option would produce. + once to automatically add a trailer with the specified _<key-alias>_, and then + called each time a `--trailer <key-alias>=<value>` argument is specified to + modify the _<value>_ of the trailer that this option would produce. + When the specified command is first called to add a trailer -with the specified <keyAlias>, the behavior is as if a special -'--trailer <keyAlias>=<value>' argument was added at the beginning -of the "git interpret-trailers" command, where <value> -is taken to be the standard output of the command with any -leading and trailing whitespace trimmed off. +with the specified _<key-alias>_, the behavior is as if a special +`--trailer <key-alias>=<value>` argument was added at the beginning +of linkgit:git-interpret-trailers[1], where _<value>_ is taken to be the +standard output of the command with any leading and trailing whitespace +trimmed off. + -If some '--trailer <keyAlias>=<value>' arguments are also passed +If some `--trailer <key-alias>=<value>` arguments are also passed on the command line, the command is called again once for each -of these arguments with the same <keyAlias>. And the <value> part +of these arguments with the same _<key-alias>_. And the _<value>_ part of these arguments, if any, will be passed to the command as its -first argument. This way the command can produce a <value> computed -from the <value> passed in the '--trailer <keyAlias>=<value>' argument. +first argument. This way the command can produce a _<value>_ computed +from the _<value>_ passed in the `--trailer <key-alias>=<value>` +argument. |