revision.h: introduce blob/tree walking in order of the commits
[gitweb.git] / Documentation / git-interpret-trailers.txt
index 31cdeaecdfde8fb358c35c3a9a2e3c4279d440d0..9dd19a1dd9f126fbf54f1dc628b30fbe05445cf3 100644 (file)
@@ -3,24 +3,27 @@ git-interpret-trailers(1)
 
 NAME
 ----
-git-interpret-trailers - help add structured information into commit messages
+git-interpret-trailers - add or parse structured information in commit messages
 
 SYNOPSIS
 --------
 [verse]
-'git interpret-trailers' [--in-place] [--trim-empty] [(--trailer <token>[(=|:)<value>])...] [<file>...]
+'git interpret-trailers' [options] [(--trailer <token>[(=|:)<value>])...] [<file>...]
+'git interpret-trailers' [options] [--parse] [<file>...]
 
 DESCRIPTION
 -----------
-Help adding 'trailers' lines, that look similar to RFC 822 e-mail
+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. 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.
+<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
@@ -80,6 +83,45 @@ OPTIONS
        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'.
+
+--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'.
+
+--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'.
+
+--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`.
+
 CONFIGURATION VARIABLES
 -----------------------
 
@@ -170,8 +212,8 @@ trailer.<token>.where::
        configuration variable and it overrides what is specified by
        that option for trailers with the specified <token>.
 
-trailer.<token>.ifexist::
-       This option takes the same values as the 'trailer.ifexist'
+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>.