git shortlog --committer=name is documented, alas not implemented

git shortlog --committer=name is documented, alas not implemented

[Gerald Pfeifer]

`man git shortlog` (from git 2.45.0) has the following:

   --author=<pattern>, --committer=<pattern>
       Limit the commits output to ones with author/committer header lines 
       that match the specified pattern (regular expression). With more 
       than one --author=<pattern>, commits whose author matches any of 
       the given patterns are chosen (similarly for multiple 
       --committer=<pattern>).

Now `git shortlog --author=gerald` works as expected.

However `git shortlog --committer=gerald` results in an error:

  error: option `committer' takes no value

This is either a doc bug or an implementation issue?


Also, how does one list all commits by a certain committer (as opposed 
to author) then?


Thanks,
Gerald

Re: git shortlog --committer=name is documented, alas not implemented

[Georg Pfuetzenreuter]

On 5/11/24 14:34, Gerald Pfeifer wrote:
> `man git shortlog` (from git 2.45.0) has the following:
> 
>     --author=<pattern>, --committer=<pattern>
>         Limit the commits output to ones with author/committer header lines
>         that match the specified pattern (regular expression). With more
>         than one --author=<pattern>, commits whose author matches any of
>         the given patterns are chosen (similarly for multiple
>         --committer=<pattern>).
> 
> Now `git shortlog --author=gerald` works as expected.
> 
> However `git shortlog --committer=gerald` results in an error:
> 
>    error: option `committer' takes no value
> 
> This is either a doc bug or an implementation issue?
> 
> 
> Also, how does one list all commits by a certain committer (as opposed
> to author) then?
> 
> 
> Thanks,
> Gerald
> 

I think this is not implemented for shortlog, and the man page is 
confusing. The --author=<pattern>/--committer=<pattern> section in 
git-shortlog(1) (Documentation/git-shortlog.txt) is just included from 
git-rev-list(1) (Documentation/rev-list-options.txt), but only the 
--committer argument documented in the "parent" git-shortlog.txt is valid.

Re: git shortlog --committer=name is documented, alas not implemented

[Junio C Hamano]

Gerald Pfeifer <gerald@pfeifer.com> writes:

> `man git shortlog` (from git 2.45.0) has the following:
>
>    --author=<pattern>, --committer=<pattern>
>        Limit the commits output to ones with author/committer header lines 
>        that match the specified pattern (regular expression). With more 
>        than one --author=<pattern>, commits whose author matches any of 
>        the given patterns are chosen (similarly for multiple 
>        --committer=<pattern>).
>
> Now `git shortlog --author=gerald` works as expected.
>
> However `git shortlog --committer=gerald` results in an error:
>
>   error: option `committer' takes no value
>
> This is either a doc bug or an implementation issue?

It is a UI and documentation issue.

For those who do not want to understand the underlying issue, a
workaround is to use the "shortlog" in the fitler mode, and use a
separate "log" as the commit selector, e.g.

    $ git log --pretty=fuller --committer=gerald |
      git shortlog [--committer] [-s] ...

The upstream of this pipeline finds only commits by gerald and shows
them with both Author: and Committer: header lines.  The downstream
of this pipeline reads the "log" stream, and does the usual "shortlog"
thing as a filter.

The "--committer" option of the "shortlog" command does not take a
value; it is a boolean that tells the command "I know you usually
group commits by authors, but in this invocation I want you to group
them by committers".  So if you have multiple "--committer=<who>"
things on the upstream "git log" side, you can sift these commits by
committer on the downstream "git shortlog".

Now for those who want to understand the underlying issue, the
"shortlog" command works in two modes.  One is the filtering mode we
just saw.  The other, which is more commonly used these days, is to
invoke the "git log" command that it reads from in the "filtering"
mode internally.  Which means that "shortlog" command now needs to
understand options and arguments for "git log" family of commands,
like

 - limiting the commits to a revision range, e.g.,
   "v2.44.0..v2.45.0",

 - finding patterns in the commit object, e.g., "--grep=<pattern>"
   and "--author gerald",

 - limiting the commits that touch specified paths, e.g.,
   "Documentation/"

as well as its own options, like "-s" "-n" "--committer", that
affects how it summarizes the "log" stream.

So, now you see where one of the two problems you observed, i.e. the
manual page talks about --author=<who> and --committer=<who>
limiting, comes from.  It is because the documentation of the
"shortlog" command tries to borrow from parts of the documentation
of the "log" command.

And the other one you observed is now easy to understand. As the
"shortlog" needs "--committer" as a boolean "are we grouping with
the committer?", it thinks that you told it to do that but by
mistake you added the option an unwanted value when you said
"--committer=gerald".

An 80%-OK-fix may be to teach the command option parser of shortlog
that "--committer" (which it currently thinks is a strict boolean)
is now an option that takes an optiona value, and when it is given
with a value, ignore it and pass it down to the underlying "git log".
Unlike the real "git log" where you can say "git log --committer gerald",
with such a fix, you can only say "git shortlog --committer=gerald" (i.e.,
you are forced to use the "--option=value" form and "--option value" form
is not allowed), but that may probably be OK.

With such a 80%-OK-fix, the documentation bug will disappear, which
would be a big plus ;-)