about summary refs log tree commit diff
path: root/third_party/git/Documentation/git-interpret-trailers.txt
diff options
context:
space:
mode:
Diffstat (limited to 'third_party/git/Documentation/git-interpret-trailers.txt')
-rw-r--r--third_party/git/Documentation/git-interpret-trailers.txt390
1 files changed, 0 insertions, 390 deletions
diff --git a/third_party/git/Documentation/git-interpret-trailers.txt b/third_party/git/Documentation/git-interpret-trailers.txt
deleted file mode 100644
index 96ec6499f001..000000000000
--- a/third_party/git/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