Re: [PATCH 5/5] git-shortlog.txt: make SYNOPSIS match log, update OPTIONS
From: Junio C Hamano <hidden>
Date: 2016-06-15 22:56:56
Ramkumar Ramachandra [off-list ref] 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.
quoted hunk
@@ -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.