git-for-windows/git
1
0
Fork 0
mirror of https://github.com/git-for-windows/git.git synced 2026-06-14 05:33:00 -05:00
Code Issues Packages Projects Releases 335 Wiki Activity

doc: interpret-trailers: stop fixating on RFC 822

Browse Source 
This command handles the trailers metadata format. But the command
isn’t introduced as such; it is instead introduced by stating that
these trailer lines look similar to RFC 822 email headers.

This is overwrought; most people do not deal directly with email
headers, and certainly not email RFCs.

Trailers are just key–value pairs that, like email headers, use colon
as the separator. The format in its simplest form is easy to describe
directly without comparing it to anything else; we will do that in the
upcoming commit “explain the format after the intro”.

For now, let’s:

• remove the first mention of email headers;
• keep the second, innocuous comparison with email line folding in the
  middle; and
• remove the now-unneeded disclaimer that trailers do not share many of
  the features of RFC 822 email headers—there is no invitation to
  speculate that trailers would follow any other email format rules
  since we do not compare them directly any more.

***

Talking about trailers as an RFC 822/2822-like format seems to go back
to the `--fixes`/`Fixes:` trailer topic,[1] the thread that precipitated
this command and in turn the first trailer support in git(1) beyond
adding s-o-b lines.

† 1: https://lore.kernel.org/all/20131027071407.GA11683@leaf/

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-06-10 23:21:19 +02:00
committed by Junio C Hamano
parent 270e10ad6d
commit 79ab4e6cd2
1 changed files with 3 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -14,9 +14,9 @@ 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 _trailer_ lines at the end of the otherwise
free-form part of a commit message. For example, in the following commit
message
------------------------------------------------
subject
@@ -107,9 +107,6 @@ 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.
OPTIONS
-------
`--in-place`::