dilim/git
1
0
Fork 0
mirror of https://github.com/git/git.git synced 2026-08-08 09:02:01 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: interpret-trailers: commit to “trailer block” term

Browse Source 
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.

Also note that we simplify the “blank line” point. The text says:

    A blank line will be added before the new trailer if there isn't one
    already.

But this isn’t quite coherent. The previous sentence says “If there is
no existing trailer”, so we are in one of these modes:

1. discussing trailer blocks in general; or
2. discussing creating a new trailer block in particular.

If (1), then we shouldn’t add a blank line before the new trailer if
there exists a trailer block already. And if (2), then the “if there
isn’t one already” is redundant.[2] So just talking about the higher-
level “trailer block” simplifies the text, since we don’t have to worry
about the different contexts that *trailers* can find themselves in.

† 1: in commit “explain the format after the intro”
† 2: Note that non-trailer lines don’t matter here; if you have a
     trailer block consisting of `(cherry picked from commit <commit>)`,
     then you still shouldn’t insert a blank line before the new trailer
     since that would create a new trailer block

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Kristoffer Haugsbakk
2026-07-30 11:18:22 +02:00
committed by Junio C Hamano
parent 6826a62435
commit b369d18b08
1 changed files with 13 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
Documentation/git-interpret-trailers.adoc
View File

@@ -74,19 +74,21 @@ 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 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.
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 will be inserted before the
new trailer block in that case.
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
Existing trailers are extracted from the input by looking for the
trailer block. A trailer block 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 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).
The trailer block is by definition at the end of the commit message.
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