[PATCH] doc: shortlog: put back trailer paragraphs

[PATCH] doc: shortlog: put back trailer paragraphs

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

47beb37b (shortlog: match commit trailers with --group, 2020-09-27)
added the `trailer` bullet point with three paragraphs.[1] Later,
3dc95e09 (shortlog: support arbitrary commit format `--group`s,
2022-10-24) put the single-paragraph bullet point about `format` right
after the first paragraph about `trailer`. That meant that the second
and third paragraphs for `trailer` got moved to `format`.

Move the two paragraphs back to `trailer`. We now also need one blank
line before the final bullet point so that it does not get joined with
the second bullet point.

† 1: Technically the bullet list formatting was immediately fixed to
     include all three paragraphs in 63d24fa0 (shortlog: allow multiple
     groups to be specified, 2020-09-27)

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-shortlog.adoc | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-shortlog.adoc b/Documentation/git-shortlog.adoc
index aa92800c69c..a11b57c1cd7 100644
--- a/Documentation/git-shortlog.adoc
+++ b/Documentation/git-shortlog.adoc
@@ -64,9 +64,6 @@ Each pretty-printed commit will be rewrapped before it is shown.
    example, if your project uses `Reviewed-by` trailers, you might want
    to see who has been reviewing with
    `git shortlog -ns --group=trailer:reviewed-by`.
- - `format:<format>`, any string accepted by the `--format` option of
-   'git log'. (See the "PRETTY FORMATS" section of
-   linkgit:git-log[1].)
 +
 Note that commits that do not include the trailer will not be counted.
 Likewise, commits with multiple trailers (e.g., multiple signoffs) may
@@ -77,6 +74,10 @@ Shortlog will attempt to parse each trailer value as a `name <email>`
 identity. If successful, the mailmap is applied and the email is omitted
 unless the `--email` option is specified. If the value cannot be parsed
 as an identity, it will be taken literally and completely.
+
+ - `format:<format>`, any string accepted by the `--format` option of
+   'git log'. (See the "PRETTY FORMATS" section of
+   linkgit:git-log[1].)
 --
 +
 If `--group` is specified multiple times, commits are counted under each

base-commit: 9a2fb147f2c61d0cab52c883e7e26f5b7948e3ed
-- 
2.53.0.13.gc85a2adbf80

Re: [PATCH] doc: shortlog: put back trailer paragraphs

[Jeff King]

On Mon, Feb 02, 2026 at 06:59:42PM +0100, kristofferhaugsbakk@fastmail.com wrote:

> 47beb37b (shortlog: match commit trailers with --group, 2020-09-27)
> added the `trailer` bullet point with three paragraphs.[1] Later,
> 3dc95e09 (shortlog: support arbitrary commit format `--group`s,
> 2022-10-24) put the single-paragraph bullet point about `format` right
> after the first paragraph about `trailer`. That meant that the second
> and third paragraphs for `trailer` got moved to `format`.
> 
> Move the two paragraphs back to `trailer`. We now also need one blank
> line before the final bullet point so that it does not get joined with
> the second bullet point.

Yeah, the change in 3dc95e09 was obviously wrong. The results look good
here, via both doc-diff output and just eyeballing the generated .html
file. Thanks for catching this.

-Peff

Re: [PATCH] doc: shortlog: put back trailer paragraphs

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> On Mon, Feb 02, 2026 at 06:59:42PM +0100, kristofferhaugsbakk@fastmail.com wrote:
>
>> 47beb37b (shortlog: match commit trailers with --group, 2020-09-27)
>> added the `trailer` bullet point with three paragraphs.[1] Later,
>> 3dc95e09 (shortlog: support arbitrary commit format `--group`s,
>> 2022-10-24) put the single-paragraph bullet point about `format` right
>> after the first paragraph about `trailer`. That meant that the second
>> and third paragraphs for `trailer` got moved to `format`.
>> 
>> Move the two paragraphs back to `trailer`. We now also need one blank
>> line before the final bullet point so that it does not get joined with
>> the second bullet point.
>
> Yeah, the change in 3dc95e09 was obviously wrong. The results look good
> here, via both doc-diff output and just eyeballing the generated .html
> file. Thanks for catching this.

Thanks, both.

[PATCH v2] doc: shortlog: put back trailer paragraphs

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

47beb37b (shortlog: match commit trailers with --group, 2020-09-27)
added the `trailer` bullet point with three paragraphs.[1] Later,
3dc95e09 (shortlog: support arbitrary commit format `--group`s,
2022-10-24) put the single-paragraph bullet point about `format` right
after the first paragraph about `trailer`. That meant that the second
and third paragraphs for `trailer` got moved to `format`.

Move the two paragraphs back to `trailer`. We now also need one blank
line before the final bullet point so that it does not get joined with
the second bullet point.

† 1: Technically the bullet list formatting was immediately fixed to
     include all three paragraphs in 63d24fa0 (shortlog: allow multiple
     groups to be specified, 2020-09-27)

Acked-by: Jeff King <peff@peff.net>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2: add ack

 Documentation/git-shortlog.adoc | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-shortlog.adoc b/Documentation/git-shortlog.adoc
index aa92800c69c..a11b57c1cd7 100644
--- a/Documentation/git-shortlog.adoc
+++ b/Documentation/git-shortlog.adoc
@@ -64,9 +64,6 @@ Each pretty-printed commit will be rewrapped before it is shown.
    example, if your project uses `Reviewed-by` trailers, you might want
    to see who has been reviewing with
    `git shortlog -ns --group=trailer:reviewed-by`.
- - `format:<format>`, any string accepted by the `--format` option of
-   'git log'. (See the "PRETTY FORMATS" section of
-   linkgit:git-log[1].)
 +
 Note that commits that do not include the trailer will not be counted.
 Likewise, commits with multiple trailers (e.g., multiple signoffs) may
@@ -77,6 +74,10 @@ Shortlog will attempt to parse each trailer value as a `name <email>`
 identity. If successful, the mailmap is applied and the email is omitted
 unless the `--email` option is specified. If the value cannot be parsed
 as an identity, it will be taken literally and completely.
+
+ - `format:<format>`, any string accepted by the `--format` option of
+   'git log'. (See the "PRETTY FORMATS" section of
+   linkgit:git-log[1].)
 --
 +
 If `--group` is specified multiple times, commits are counted under each

Interdiff against v1:

Range-diff against v1:
1:  e3cdf4b44ad ! 1:  3383edc5164 doc: shortlog: put back trailer paragraphs
    @@ Commit message
              include all three paragraphs in 63d24fa0 (shortlog: allow multiple
              groups to be specified, 2020-09-27)
     
    +    Acked-by: Jeff King <peff@peff.net>
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
    +
    + ## Notes (series) ##
    +    v2: add ack
    +
      ## Documentation/git-shortlog.adoc ##
     @@ Documentation/git-shortlog.adoc: Each pretty-printed commit will be rewrapped before it is shown.
         example, if your project uses `Reviewed-by` trailers, you might want

base-commit: 9a2fb147f2c61d0cab52c883e7e26f5b7948e3ed
-- 
2.53.0.13.gc85a2adbf80