From: Junio C Hamano <gitster@pobox.com>
To: Gerald Pfeifer <gerald@pfeifer.com>
Cc: git@vger.kernel.org
Subject: Re: git shortlog --committer=name is documented, alas not implemented
Date: Sat, 11 May 2024 09:17:38 -0700 [thread overview]
Message-ID: <xmqqfruo1fx9.fsf@gitster.g> (raw)
In-Reply-To: <77e42d15-fcaf-5c1b-3a00-f1f1e3cedfc4@pfeifer.com> (Gerald Pfeifer's message of "Sat, 11 May 2024 14:34:12 +0200 (CEST)")
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 ;-)
prev parent reply other threads:[~2024-05-11 16:17 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-05-11 12:34 git shortlog --committer=name is documented, alas not implemented Gerald Pfeifer
2024-05-11 13:12 ` Georg Pfuetzenreuter
2024-05-11 16:17 ` Junio C Hamano [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=xmqqfruo1fx9.fsf@gitster.g \
--to=gitster@pobox.com \
--cc=gerald@pfeifer.com \
--cc=git@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).