Re: [PATCH 5/5] git-shortlog.txt: make SYNOPSIS match log, update OPTIONS

[Junio C Hamano <gitster@pobox.com>]

Ramkumar Ramachandra <artagnon@gmail.com> writes:

> +<since>..<until>::
> +	Consider only commits between the named two revisions.  When
> +	either <since> or <until> is omitted, it defaults to `HEAD`,
> +	i.e. the tip of the current branch.  For a more complete list
> +	of ways to spell <since>..<until>, see
> +	linkgit:gitrevisions[7].
> +

The same "revision range" comment, and also that this should be
after all options and before "-- <pathspec>", apply to this.

> @@ -56,6 +63,16 @@ OPTIONS
>  If width is `0` (zero) then indent the lines of the output without wrapping
>  them.
>  
> +[\--] <path>...::
> +	Consider only commits that are enough to explain how the files
> +	that match the specified paths came to be.  See "History
> +	Simplification" below for details and other simplification
> +	modes.
> ++
> +Paths may need to be prefixed with "\-- " to separate them from
> +options or revisions, when confusion arises.
> +
> +include::rev-list-options.txt[]

While it is true that this page is missing many options, including
rev-list-options.txt as-is is more harmful than helpful and the
patch needs more work (hint: with "ifdef::git-shortlog[]" sprinkled
in rev-list-options.txt).

Some of the earlier one in rev-list-options are fine, but some
others are inappropriate in the context of shortlog.  For example,
--grep=<pattern>, while it would internally work as it is told to
do, is unlikely to be clear how well/correctly worked when viewing
the end result.  So are many others, such as --all-match,
--walk-reflogs, --sparse, etc.  Some e.g. --topo-order, do not make
sense at all.

I am not sure what the command would do if you give --stdin; the
command wants to read from the standard input to operate as a filter
for "git log" output, but the "--stdin" from rev-list family wants
to read revision range specifiers from the standard input.  I do not
think it is something any sane user would want to do.