kernel
/
git
mirror of https://git.kernel.org/pub/scm/git/git.git
1
0
Fork 0
Code Releases Activity

doc: interpret-trailers: rewrite new-trailers paragraphs 

Two commits ago we moved new-trailers paragraph next to each other.
But there is something curious about two of them:

    By default the new trailer will appear at the end of the trailer
    block. [...]

Then a source block and a paragraph later:

    By default, a `<key>=<value>` or `<key>:<value>` argument given
    using `--trailer` will be appended after the existing trailers only
    if [...]

Why are there two paragraphs that talk about how “By default” a trailer
will be appended?

We can make these paragraphs flow better, and with a more distinct
character each, by dividing the flow like this:

1. Declare that we are about to talk about `--trailer` appending
2. Explain the default behavior
3. Explain how this affects the trailer block
4. Then discuss what each trailer line will look like

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
main
Kristoffer Haugsbakk 2026-08-09 22:06:34 +02:00 committed by Junio C Hamano
parent 4d45e571ae
commit cb657364d5
1 changed files with 12 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -60,10 +60,18 @@ are applied to each input and the way any existing trailer in
the input is changed. They also make it possible to
automatically add some trailers.

By default, a `<key>=<value>` or `<key>:<value>` argument given
using `--trailer` will be appended after the existing trailers only if
the last trailer has a different (_<key>_, _<value>_) pair (or if there
is no existing trailer). The _<key>_ and _<value>_ parts will be trimmed
Let's consider new trailers added with `--trailer`.
By default, the new trailer will appear at the end of the trailer block.
Also by default, this new trailer will only be added
if the last trailer is different to it.
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.

This is how the new trailer is added: a `<key>=<value>` or
`<key>:<value>` argument given using `--trailer` will be appended after
the existing trailers. The _<key>_ and _<value>_ parts will be trimmed
to remove starting and trailing whitespace, and the resulting trimmed
_<key>_ and _<value>_ will appear in the output like this:

@ -74,12 +82,6 @@ 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 will be inserted before the
new trailer block in that case.

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