Re: [PATCH v3 2/4] Documentation: clarify 'complete message'

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 7, 2020, 19:19 UTC
Message-ID: <xmqqwo3f3zg3.fsf@gitster.c.googlers.com>
In-Reply-To: <20200707174049.21714-3-chriscool@tuxfamily.org>

Christian Couder <christian.couder@gmail.com> writes:

Show 21 quoted lines

> In Documentation/git-for-each-ref.txt let's clarify what
> we mean by "complete message".
>
> Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
> ---
>  Documentation/git-for-each-ref.txt | 5 +++--
>  1 file changed, 3 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
> index 2db9779d54..788258c3ad 100644
> --- a/Documentation/git-for-each-ref.txt
> +++ b/Documentation/git-for-each-ref.txt
> @@ -232,8 +232,9 @@ Fields that have name-email-date tuple as its value (`author`,
>  `committer`, and `tagger`) can be suffixed with `name`, `email`,
>  and `date` to extract the named component.
>  
> -The complete message of a commit or tag object is `contents`. This
> -field can also be used in the following ways:
> +The complete message (subject, body, trailers and signature) of a
> +commit or tag object is `contents`. This field can also be used in the
> +following ways:

Hmph, I regret asking what is "complete", i.e. as opposed to what.

The above makes it even unclear if things like "signature on commit" is part of the complete message. I _think_ you meant the part after stripping the object header, so "signature in a signed tag is part of 'complete message', while signature in a signed commit is not", which feels somewhat strange.

But then, it may be easier to understand if we said

    The message in a commit or a tag object is `contents`, from
    which `contents:<part>` can be used to extract various parts out
    of.

without introducing "complete".

In any case I think patches 1 & 2 are definite improvement.

Thanks.