Re: [PATCH v3 1/4] Documentation: clarify %(contents:XXXX) doc

From: Junio C Hamano <gitster@pobox.com>
To: Christian Couder <christian.couder@gmail.com>
Cc: git@vger.kernel.org, Jeff King <peff@peff.net>,
	Christian Couder <chriscool@tuxfamily.org>
Subject: Re: [PATCH v3 1/4] Documentation: clarify %(contents:XXXX) doc
Date: Tue, 07 Jul 2020 12:26:53 -0700	[thread overview]
Message-ID: <xmqqsge33z42.fsf@gitster.c.googlers.com> (raw)
In-Reply-To: <20200707174049.21714-2-chriscool@tuxfamily.org> (Christian Couder's message of "Tue, 7 Jul 2020 19:40:46 +0200")

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

> +The complete message of a commit or tag object is `contents`. This
> +field can also be used in the following ways:
> +
> +contents:subject::
> +	The "subject" of the commit or tag message.  It's actually the
> +	concatenation of all lines of the commit message up to the
> +	first blank line.

Let's avoid confusing readers by saying "A is X. It's actually Y".

    The first paragraph of the message, which typically is a single
    line, is taken as the "subject" of the commit or the tag
    message.

> +contents:body::
> +	The "body" of the commit or tag message.  It's made of the
> +	lines after the first blank line.

    The remainder of the commit or the tag message that follows the
    "subject".

> +contents:signature::
> +	The optional GPG signature.

I _think_ this only applies to signed tag objects and not signed
commit objects, but this text does not help to decide if I am
right.

> +contents:lines=N::
> +	The first `N` lines of the message.

Good.