Re: [PATCH 8/8] shortlog: allow multiple groups to be specified

[Eric Sunshine <sunshine@sunshineco.com>]

On Fri, Sep 25, 2020 at 3:05 AM Jeff King <peff@peff.net> wrote:
> This patch teaches shortlog to accept multiple --group options on the
> command line, and pull data from all of them. That makes it possible to
> run:
> [...]
> Signed-off-by: Jeff King <peff@peff.net>
> ---
> diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt
> @@ -69,6 +69,11 @@ 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.
> ++
> +If `--group` is specified multiple times, commits are counted under each
> +value (but again, only once per unique value in that commit). For
> +example, `git shortlog --group=author --group=trailer:co-authored-by`
> +counts both authors and co-authors.

Intuitively, I understand (or hope) that the first use of --group
overrides what is otherwise collected by default (authors), however,
would there be value in stating this explicitly?

At this point, the documentation for --committer still says:

    --committer::
        Collect and show committer identities instead of authors.
        This is an alias for `--group=committer`.

which stops feeling accurate now that --group can be specified more
than once. The "instead of authors" bit is particularly jarring. I
wonder if the first sentence can simply be dropped.