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

doc: interpret-trailers: rewrite new-trailers paragraphs

Browse Source 
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>
This commit is contained in:
Kristoffer Haugsbakk
2026-07-30 11:18:23 +02:00
committed by Junio C Hamano
parent b369d18b08
commit 55afc1f9aa
1 changed files with 12 additions and 10 deletions
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