Skip to content

Commit dd19621

Browse files
LemmingAvalanchegitster
authored andcommitted
doc: interpret-trailers: commit to “trailer block” term
We chose to introduce the term “trailer block” into the documentation a few commits ago.[1] It is used in the code though, so it is not a newly invented term. That term was useful to explain where the trailers are found (they *trail* the message). But it is also useful here, where we explain how trailers are added to existing messages, how trailer blocks are found (beyond the simple case in the introduction), and how the end of the message is found. † 1: in commit “explain the format after the intro” Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name> Signed-off-by: Junio C Hamano <gitster@pobox.com>
1 parent 0e701f8 commit dd19621

File tree

1 file changed

+14
-12
lines changed

1 file changed

+14
-12
lines changed

Documentation/git-interpret-trailers.adoc

Lines changed: 14 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -87,19 +87,21 @@ trailer.sign.key "Signed-off-by: "
8787
in your configuration, you only need to specify `--trailer="sign: foo"`
8888
on the command line instead of `--trailer="Signed-off-by: foo"`.
8989

90-
By default the new trailer will appear at the end of all the existing
91-
trailers. If there is no existing trailer, the new trailer will appear
92-
at the end of the input. A blank line will be added before the new
93-
trailer if there isn't one already.
94-
95-
Existing trailers are extracted from the input by looking for
96-
a group of one or more lines that (i) is all trailers, or (ii) contains at
97-
least one Git-generated or user-configured trailer and consists of at
90+
By default the new trailer will appear at the end of the trailer block.
91+
A trailer block will be created with only that trailer if a trailer
92+
block does not already exist. Recall that a trailer block needs to be
93+
preceded by a blank line, so a blank line (specifically an empty line)
94+
will be inserted before the new trailer block in that case.
95+
96+
Existing trailers are extracted from the input by looking for the
97+
trailer block. Concretely, that is a group of one or more lines that (i)
98+
is all trailers, or (ii) contains at least one Git-generated or
99+
user-configured trailer and consists of at
98100
least 25% trailers.
99-
The group must be preceded by one or more empty (or whitespace-only) lines.
100-
The group must either be at the end of the input or be the last
101-
non-whitespace lines before a line that starts with `---` (followed by a
102-
space or the end of the line).
101+
The trailer block is by definition at the end the the message. The end
102+
of the message in turn is either (i) at the end of the input, or (ii)
103+
the last non-whitespace lines before a line that starts with `---`
104+
(followed by a space or the end of the line).
103105

104106
When reading trailers, there can be no whitespace before or inside the
105107
_<key>_, but any number of regular space and tab characters are allowed

0 commit comments

Comments
 (0)