From: Junio C Hamano <gitster@pobox.com>
Date: Mon, 08 May 2023 19:50:16 GMT
Subject: Re: [PATCH 11/11] doc: trailer: add more examples in DESCRIPTION
Message-ID: <xmqqmt2emwlj.fsf@gitster.g>
In-Reply-To: <ea483b364b460819c727da5c65497de6ecd4b04f.1683566870.git.gitgitgadget@gmail.com>

"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.