Merge branch 'kh/doc-trailers' into jch
Documentation for 'git interpret-trailers' has been updated to explain the format of trailer keys (alphanumeric characters and hyphens), replace outdated terminology, define key terms upfront, and document how comment lines in the input are treated. * kh/doc-trailers: doc: interpret-trailers: document comment line treatment doc: interpret-trailers: commit to “trailer block” term doc: interpret-trailers: join new-trailers again doc: interpret-trailers: add key format example doc: interpret-trailers: explain key format doc: interpret-trailers: explain the format after the intro doc: interpret-trailers: not just for commit messages doc: interpret-trailers: use “metadata” in Name as well doc: interpret-trailers: replace “lines” with “metadata” doc: interpret-trailers: stop fixating on RFC 822
Junio C Hamano
commit
d42abd1627
|
|
@ -3,7 +3,7 @@ git-interpret-trailers(1)
|
|||
|
||||
NAME
|
||||
----
|
||||
git-interpret-trailers - Add or parse structured information in commit messages
|
||||
git-interpret-trailers - Add or parse metadata in commit messages
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
|
|
@ -14,9 +14,15 @@ git interpret-trailers [--in-place] [--trim-empty]
|
|||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
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
|
||||
Add or parse trailers metadata at the end of the otherwise
|
||||
free-form part of a commit message, or any other kind of text.
|
||||
|
||||
A _trailer_ in its simplest form is a key-value pair with a colon as a
|
||||
separator. The _key_ consists of ASCII alphanumeric characters and
|
||||
hyphens (`-`). A _trailer block_ consists of one or more trailers. The
|
||||
trailer block needs to be preceded by a blank line, where a _blank line_
|
||||
is either an empty or a whitespace-only line. For example, in the
|
||||
following commit message
|
||||
|
||||
------------------------------------------------
|
||||
subject
|
||||
|
|
@ -68,6 +74,22 @@ key: value
|
|||
This means that the trimmed _<key>_ and _<value>_ will be separated by
|
||||
"`:`{nbsp}" (one colon followed by one space).
|
||||
|
||||
By default the new trailer will appear at the end of the trailer block.
|
||||
A trailer block will be created with only that trailer if a trailer
|
||||
block does not already exist. Recall that a trailer block needs to be
|
||||
preceded by a blank line, so a blank line (specifically an empty line)
|
||||
will be inserted before the new trailer block in that case.
|
||||
|
||||
Existing trailers are extracted from the input by looking for the
|
||||
trailer block. Concretely, that is 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 trailer block is by definition at the end the the message. The end
|
||||
of the message in turn is either (i) at the end of the input, or (ii)
|
||||
the last non-whitespace lines before a line that starts with `---`
|
||||
(followed by a space or the end of the line).
|
||||
|
||||
For convenience, a _<key-alias>_ can be configured to make using `--trailer`
|
||||
shorter to type on the command line. This can be configured using the
|
||||
`trailer.<key-alias>.key` configuration variable. The _<key-alias>_ must be a prefix
|
||||
|
|
@ -81,20 +103,6 @@ trailer.sign.key "Signed-off-by: "
|
|||
in your configuration, you only need to specify `--trailer="sign: foo"`
|
||||
on the command line instead of `--trailer="Signed-off-by: foo"`.
|
||||
|
||||
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
|
||||
at the end of the input. A blank line will be added before the new
|
||||
trailer if there isn't one already.
|
||||
|
||||
Existing trailers are extracted from the input 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 input or be the last
|
||||
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
|
||||
_<key>_, but any number of regular space and tab characters are allowed
|
||||
between the _<key>_ and the separator. There can be whitespaces before,
|
||||
|
|
@ -107,8 +115,15 @@ key: This is a very long value, with spaces and
|
|||
newlines in it.
|
||||
------------------------------------------------
|
||||
|
||||
Note that trailers do not follow (nor are they intended to follow) many of the
|
||||
rules for RFC 822 headers. For example they do not follow the encoding rule.
|
||||
OTHER RULES
|
||||
-----------
|
||||
|
||||
What was covered in the previous section are the rules that are relevant
|
||||
for regular use. The following points are included for completeness.
|
||||
|
||||
This command ignores comment lines (see `core.commentString` in
|
||||
linkgit:git-config[1]). This is for use with the `prepare-commit-msg`
|
||||
and `commit-msg` hooks.
|
||||
|
||||
OPTIONS
|
||||
-------
|
||||
|
|
@ -402,6 +417,29 @@ mv "\$1.new" "\$1"
|
|||
$ chmod +x .git/hooks/commit-msg
|
||||
------------
|
||||
|
||||
* Here we try to to use three different trailer keys. But it fails
|
||||
because two of them are not recognized as trailer keys.
|
||||
+
|
||||
----
|
||||
$ cat msg.txt
|
||||
subject
|
||||
|
||||
Skapad-på: some-branch
|
||||
Hash-in-v6.11: 45c12d3269fe48f22834320c782ffe86c3560f2c
|
||||
Reviewed-by: Alice <alice@example.com>
|
||||
$ git interpret-trailers --only-trailers <msg.txt
|
||||
$
|
||||
----
|
||||
+
|
||||
Recall that a trailer key has to consist of only ASCII alphanumeric
|
||||
characters and hyphens, and this does not hold for the two first
|
||||
supposed trailer keys. And now none are recognized as trailers because
|
||||
the candidate trailer block has at least one non-trailer line, even
|
||||
though `Reviewed-by` is a valid trailer key. Recall that a trailer block
|
||||
has to either (i) be all trailers, or (ii) consist of at least one
|
||||
Git-generated or user-configured trailer (and some other conditions).
|
||||
And (ii) is not satisfied since we have not configured any trailer keys.
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
linkgit:git-commit[1], linkgit:git-format-patch[1], linkgit:git-config[1]
|
||||
|
|
|
|||
Loading…
Reference in New Issue