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

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 21, 2013, 07:04 UTC
Message-ID: <7vppxowej9.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1366458313-7186-6-git-send-email-artagnon@gmail.com>

Ramkumar Ramachandra <artagnon@gmail.com> writes:

Show 7 quoted lines

> +<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.

Show 14 quoted lines

> @@ -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.