| Message ID | ea483b364b460819c727da5c65497de6ecd4b04f.1683566870.git.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | docs: interpret-trailers: reword and add examples | expand |
"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes: > From: Linus Arver <linusa@google.com> > > 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> > --- > Documentation/git-interpret-trailers.txt | 20 ++++++++++++++++++-- > 1 file changed, 18 insertions(+), 2 deletions(-) > > diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt > index 119dcd64f34..f31b94a6823 100644 > --- a/Documentation/git-interpret-trailers.txt > +++ b/Documentation/git-interpret-trailers.txt > @@ -16,7 +16,18 @@ 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. > +message. For example, in the following commit message > + > +------------------------------------------------ > +subject > + > +message > + > +Signed-off-by: Alice <alice@example.com> > +Signed-off-by: Bob <bob@example.com> > +------------------------------------------------ > + > +the last two lines starting with "Signed-off-by" are trailers. Excellent. > @@ -68,7 +79,12 @@ When reading trailers, there can be no whitespace before or inside the > between the <token> and the separator. There can be whitespaces before, > inside or after the <value>. The <value> may be split over multiple lines > with each subsequent line starting with at least one whitespace, like > -the "folding" in RFC 822. > +the "folding" in RFC 822. Example: > + > +------------------------------------------------ > +token: Lorem ipsum dolor sit amet, consectetur > + adipiscing elit. > +------------------------------------------------ Excellent.
diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt index 119dcd64f34..f31b94a6823 100644 --- a/Documentation/git-interpret-trailers.txt +++ b/Documentation/git-interpret-trailers.txt @@ -16,7 +16,18 @@ 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. +message. For example, in the following commit message + +------------------------------------------------ +subject + +message + +Signed-off-by: Alice <alice@example.com> +Signed-off-by: Bob <bob@example.com> +------------------------------------------------ + +the last two lines starting with "Signed-off-by" are trailers. This command reads some patches or commit messages from either the <file> arguments or the standard input if no <file> is specified. If @@ -68,7 +79,12 @@ When reading trailers, there can be no whitespace before or inside the between the <token> and the separator. There can be whitespaces before, inside or after the <value>. The <value> may be split over multiple lines with each subsequent line starting with at least one whitespace, like -the "folding" in RFC 822. +the "folding" in RFC 822. Example: + +------------------------------------------------ +token: Lorem ipsum dolor sit amet, consectetur + adipiscing elit. +------------------------------------------------ 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.