diff options
Diffstat (limited to 'Documentation/git-interpret-trailers.txt')
| -rw-r--r-- | Documentation/git-interpret-trailers.txt | 390 |
1 files changed, 0 insertions, 390 deletions
diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt deleted file mode 100644 index 96ec6499f001..000000000000 --- a/Documentation/git-interpret-trailers.txt +++ /dev/null @@ -1,390 +0,0 @@ -git-interpret-trailers(1) -========================= - -NAME ----- -git-interpret-trailers - Add or parse structured information in commit messages - -SYNOPSIS --------- -[verse] -'git interpret-trailers' [<options>] [(--trailer <token>[(=|:)<value>])...] [<file>...] -'git interpret-trailers' [<options>] [--parse] [<file>...] - -DESCRIPTION ------------ -Help parsing or 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. If -`--parse` is specified, the output consists of the parsed trailers. - -Otherwise, 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 appended after the existing trailers only if -the last trailer has a different (<token>, <value>) pair (or if there -is no existing trailer). 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 ------------------------------------------------- - -This means that the trimmed <token> and <value> will be separated by -`': '` (one colon followed by one space). - -By default the new trailer will appear at the end of all the existing -trailers. If there is no existing trailer, the new trailer will appear -after the commit message part of the output, and, if there is no line -with only spaces at the end of the commit message part, one blank line -will be added before the new trailer. - -Existing trailers are extracted from the input message by looking for -a group of one or more lines that (i) is all trailers, or (ii) contains at -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 message or be the last -non-whitespace lines before a line that starts with '---' (followed by a -space or the end of the line). Such three minus signs start the patch -part of the message. See also `--no-divider` below. - -When reading trailers, there can be whitespaces after the -token, the separator and the value. There can also be whitespaces -inside the token and the value. The value may be split over multiple lines with -each subsequent line starting with whitespace, like the "folding" in RFC 822. - -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 encoding rules and probably many other rules. - -OPTIONS -------- ---in-place:: - Edit the files in place. - ---trim-empty:: - If the <value> part of any trailer contains only whitespace, - the whole trailer will be removed from the resulting message. - This applies 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. - ---where <placement>:: ---no-where:: - Specify where all new trailers will be added. A setting - provided with '--where' overrides all configuration variables - and applies to all '--trailer' options until the next occurrence of - '--where' or '--no-where'. Possible values are `after`, `before`, - `end` or `start`. - ---if-exists <action>:: ---no-if-exists:: - Specify what action will be performed when there is already at - least one trailer with the same <token> in the message. A setting - provided with '--if-exists' overrides all 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`. - ---if-missing <action>:: ---no-if-missing:: - Specify what action will be performed when there is no other - trailer with the same <token> in the message. A setting - provided with '--if-missing' overrides all 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`. - ---only-trailers:: - Output only the trailers, not any other parts of the input. - ---only-input:: - Output only trailers that exist in the input; do not add any - from the command-line or by following configured `trailer.*` - rules. - ---unfold:: - Remove any whitespace-continuation in trailers, so that each - trailer appears on a line by itself with its full content. - ---parse:: - A convenience alias for `--only-trailers --only-input - --unfold`. - ---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`). - -CONFIGURATION VARIABLES ------------------------ - -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 - 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 '<token><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: -'<token>% <value>' (one percent sign and one space will appear between -the token and the value). - -trailer.where:: - This option tells where a new trailer will be added. -+ -This can be `end`, which is the default, `start`, `after` or `before`. -+ -If it is `end`, then each new trailer will appear at the end of the -existing trailers. -+ -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 <token>. -+ -If it is `before`, then each new trailer will appear just before the -first trailer with the same <token>. - -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 <token> in the message. -+ -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 (<token>, <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 (<token>, <value>) pair is already in the message. -+ -With `add`, a new trailer will be added, even if some trailers with -the same (<token>, <value>) pair are already in the message. -+ -With `replace`, an existing trailer with the same <token> will be -deleted and the new trailer will be added. The deleted trailer will be -the closest one (with the same <token>) 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 <token> in the message. - -trailer.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>.key:: - This `key` will be used instead of <token> in the trailer. At - the end of this 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, then the key will be used instead of both the -<token> and the default separator when adding the trailer. - -trailer.<token>.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 <token>. - -trailer.<token>.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 <token>. - -trailer.<token>.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 <token>. - -trailer.<token>.command:: - This option can be used to specify a shell command that will - be called 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 beginning 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. -+ -If some '<token>=<value>' arguments are also passed on the command -line, when a 'trailer.<token>.command' is configured, the command will -also be executed for each of these arguments. And the <value> part of -these arguments, if any, will be used to replace the `$ARG` string in -the command. - -EXAMPLES --------- - -* Configure a 'sign' trailer with a 'Signed-off-by' key, and then - add two of these trailers to a message: -+ ------------- -$ git config trailer.sign.key "Signed-off-by" -$ cat msg.txt -subject - -message -$ cat msg.txt | git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>' -subject - -message - -Signed-off-by: Alice <alice@example.com> -Signed-off-by: Bob <bob@example.com> ------------- - -* Use the `--in-place` option to edit a message file in place: -+ ------------- -$ cat msg.txt -subject - -message - -Signed-off-by: Bob <bob@example.com> -$ git interpret-trailers --trailer 'Acked-by: Alice <alice@example.com>' --in-place msg.txt -$ cat msg.txt -subject - -message - -Signed-off-by: Bob <bob@example.com> -Acked-by: Alice <alice@example.com> ------------- - -* Extract the last commit as a patch, and add a 'Cc' and a - 'Reviewed-by' trailer to it: -+ ------------- -$ git format-patch -1 -0001-foo.patch -$ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Reviewed-by: Bob <bob@example.com>' 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: -+ ------------- -$ git config trailer.sign.key "Signed-off-by: " -$ git config trailer.sign.ifmissing add -$ git config trailer.sign.ifexists doNothing -$ git config trailer.sign.command 'echo "$(git config user.name) <$(git config user.email)>"' -$ git interpret-trailers <<EOF -> EOF - -Signed-off-by: Bob <bob@example.com> -$ git interpret-trailers <<EOF -> Signed-off-by: Alice <alice@example.com> -> EOF - -Signed-off-by: Alice <alice@example.com> ------------- - -* Configure a 'fix' trailer with a key that contains a '#' and no - space after this character, and show how it works: -+ ------------- -$ git config trailer.separators ":#" -$ git config trailer.fix.key "Fix #" -$ echo "subject" | git interpret-trailers --trailer fix=42 -subject - -Fix #42 ------------- - -* Configure a 'see' trailer with a command to show the subject of a - commit that is related, and show how it works: -+ ------------- -$ git config trailer.see.key "See-also: " -$ git config trailer.see.ifExists "replace" -$ git config trailer.see.ifMissing "doNothing" -$ git config trailer.see.command "git log -1 --oneline --format=\"%h (%s)\" --abbrev-commit --abbrev=14 \$ARG" -$ git interpret-trailers <<EOF -> subject -> -> message -> -> see: HEAD~2 -> EOF -subject - -message - -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: -+ ------------- -$ sed -e 's/ Z$/ /' >commit_template.txt <<EOF -> ***subject*** -> -> ***message*** -> -> Fixes: Z -> Cc: Z -> Reviewed-by: Z -> Signed-off-by: Z -> EOF -$ git config commit.template commit_template.txt -$ cat >.git/hooks/commit-msg <<EOF -> #!/bin/sh -> git interpret-trailers --trim-empty --trailer "git-version: \$(git describe)" "\$1" > "\$1.new" -> mv "\$1.new" "\$1" -> EOF -$ chmod +x .git/hooks/commit-msg ------------- - -SEE ALSO --------- -linkgit:git-commit[1], linkgit:git-format-patch[1], linkgit:git-config[1] - -GIT ---- -Part of the linkgit:git[1] suite |