[v4,1/3] Documentation: clarify %(contents:XXXX) doc
diff mbox series

Message ID 20200710164739.6616-2-chriscool@tuxfamily.org
State New
Headers show
Series
  • Add support for %(contents:size) in ref-filter
Related show

Commit Message

Christian Couder July 10, 2020, 4:47 p.m. UTC
Let's avoid a big dense paragraph by using an unordered
list for the %(contents:XXXX) format specifiers.

While at it let's also make the following improvements:

  - Let's not describe %(contents) using "complete message"
    as it's not clear what an incomplete message is.

  - Let's improve how the "subject" and "body" are
    described.

  - Let's state that "signature" is only available for
    tag objects.

Suggested-by: Jeff King <peff@peff.net>
Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
---
 Documentation/git-for-each-ref.txt | 24 ++++++++++++++++++------
 1 file changed, 18 insertions(+), 6 deletions(-)

Comments

Junio C Hamano July 10, 2020, 8:24 p.m. UTC | #1
Christian Couder <christian.couder@gmail.com> writes:

> Let's avoid a big dense paragraph by using an unordered
> list for the %(contents:XXXX) format specifiers.
>
> While at it let's also make the following improvements:
>
>   - Let's not describe %(contents) using "complete message"
>     as it's not clear what an incomplete message is.
>
>   - Let's improve how the "subject" and "body" are
>     described.
>
>   - Let's state that "signature" is only available for
>     tag objects.
>
> Suggested-by: Jeff King <peff@peff.net>
> Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
> ---
>  Documentation/git-for-each-ref.txt | 24 ++++++++++++++++++------
>  1 file changed, 18 insertions(+), 6 deletions(-)

Looking good.  Thanks.


> diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
> index 6dcd39f6f6..b739412c30 100644
> --- a/Documentation/git-for-each-ref.txt
> +++ b/Documentation/git-for-each-ref.txt
> @@ -232,12 +232,24 @@ 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 in a commit and tag object is `contents`.
> -Its first line is `contents:subject`, where subject is the concatenation
> -of all lines of the commit message up to the first blank line.  The next
> -line is `contents:body`, where body is all of the lines after the first
> -blank line.  The optional GPG signature is `contents:signature`.  The
> -first `N` lines of the message is obtained using `contents:lines=N`.
> +The message in a commit or a tag object is `contents`, from which
> +`contents:<part>` can be used to extract various parts out of:
> +
> +contents:subject::
> +	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 remainder of the commit or the tag message that follows
> +	the "subject".
> +
> +contents:signature::
> +	The optional GPG signature of the tag.
> +
> +contents:lines=N::
> +	The first `N` lines of the message.
> +
>  Additionally, the trailers as interpreted by linkgit:git-interpret-trailers[1]
>  are obtained as `trailers` (or by using the historical alias
>  `contents:trailers`).  Non-trailer lines from the trailer block can be omitted

Patch
diff mbox series

diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
index 6dcd39f6f6..b739412c30 100644
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -232,12 +232,24 @@  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 in a commit and tag object is `contents`.
-Its first line is `contents:subject`, where subject is the concatenation
-of all lines of the commit message up to the first blank line.  The next
-line is `contents:body`, where body is all of the lines after the first
-blank line.  The optional GPG signature is `contents:signature`.  The
-first `N` lines of the message is obtained using `contents:lines=N`.
+The message in a commit or a tag object is `contents`, from which
+`contents:<part>` can be used to extract various parts out of:
+
+contents:subject::
+	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 remainder of the commit or the tag message that follows
+	the "subject".
+
+contents:signature::
+	The optional GPG signature of the tag.
+
+contents:lines=N::
+	The first `N` lines of the message.
+
 Additionally, the trailers as interpreted by linkgit:git-interpret-trailers[1]
 are obtained as `trailers` (or by using the historical alias
 `contents:trailers`).  Non-trailer lines from the trailer block can be omitted