doc: trailer: add more examples in DESCRIPTION
Be more up-front about what trailers are in practice with examples, to give the reader a visual cue while they go on to read the rest of the description. Also add an example for multiline values. Signed-off-by: Linus Arver <linusa@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Linus Arver committed
Jun 15, 2023 at 02:53 UTC
d57fa7fc73202af226b6c0e0d9788c6460ce23b9
1 file changed
+18
-2
Documentation/git-interpret-trailers.txt
+18
-2
@@ -16,7 +16,18 @@ DESCRIPTION
16
-----------
17
Add or parse 'trailer' lines that look similar to RFC 822 e-mail
18
headers, at the end of the otherwise free-form part of a commit
19
-message.
19
+message. For example, in the following commit message
20
+
21
+------------------------------------------------
22
+subject
23
+
24
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
25
+
26
+Signed-off-by: Alice <alice@example.com>
27
+Signed-off-by: Bob <bob@example.com>
28
+------------------------------------------------
29
+
30
+the last two lines starting with "Signed-off-by" are trailers.
31
32
This command reads commit messages from either the
33
<file> arguments or the standard input if no <file> is specified.
@@ -73,7 +84,12 @@ When reading trailers, there can be no whitespace before or inside the
84
between the <token> and the separator. There can be whitespaces before,
85
inside or after the <value>. The <value> may be split over multiple lines
86
with each subsequent line starting with at least one whitespace, like
76
-the "folding" in RFC 822.
87
+the "folding" in RFC 822. Example:
88
+
89
+------------------------------------------------
90
+token: This is a very long value, with spaces and
91
+ newlines in it.
92
+------------------------------------------------
93
94
Note that trailers do not follow (nor are they intended to follow) many of the
95
rules for RFC 822 headers. For example they do not follow the encoding rule.