[v2] git-shortlog.txt: include commit limiting options
diff mbox series

Message ID 20191104130858.23673-1-me@yadavpratyush.com
State New
Headers show
Series
  • [v2] git-shortlog.txt: include commit limiting options
Related show

Commit Message

Pratyush Yadav Nov. 4, 2019, 1:08 p.m. UTC
git-shortlog, like git-log, supports options to filter what commits are
used to generate the log. These options come from git-rev-list, and are
documented in Documentation/rev-list-options.txt. Include those options
in shortlog's documentation.

But since rev-list-options.txt contains some other options that don't
really apply in the context of shortlog (like diff formatting, commit
ordering, etc), add a switch in rev-list-options.txt that excludes those
sections from the shortlog documentation. To be more specific, include
only the "Commit Limiting" section.

Signed-off-by: Pratyush Yadav <me@yadavpratyush.com>
---
That ifdef covers almost the entire document. Is there a better way in
Asciidoc to do something like this?

 Documentation/git-shortlog.txt     | 3 +++
 Documentation/rev-list-options.txt | 2 ++
 2 files changed, 5 insertions(+)

--
2.21.0

Comments

Junio C Hamano Nov. 6, 2019, 1:24 a.m. UTC | #1
Pratyush Yadav <me@yadavpratyush.com> writes:

> But since rev-list-options.txt contains some other options that don't
> really apply in the context of shortlog (like diff formatting, commit
> ordering, etc), add a switch in rev-list-options.txt that excludes those
> sections from the shortlog documentation. To be more specific, include
> only the "Commit Limiting" section.

I think this is much better than duplication, and we can improve it
further with follow-up patches.

Many options for history simplification are useful for shortlog.  I
very often use "git shortlog -- cache.h" myself (i.e. limiting to
the given pathspec).  I suspect most of the "--dashed-options"
listed there would make sense for some workflows, even though I do
not use them often enough with shortlog.  The only exception I can
think of that may not be useful at all for the purose of shortlog is
"--simplify-by-decoration".

I agree with the patch that all other sections (i.e. bisection
helper, commit ordering, object traversal, commit formatting and
diff formatting) make little sense to use with shortlog.

> Signed-off-by: Pratyush Yadav <me@yadavpratyush.com>
> ---
> That ifdef covers almost the entire document. Is there a better way in
> Asciidoc to do something like this?

I would have excluded each section independently with "Heh, this
part is not needed for shortlog"; that would make it less error
prone against future shuffling of sections in the file.

Thanks.

Patch
diff mbox series

diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt
index bc80905a8a..a72ea7f7ba 100644
--- a/Documentation/git-shortlog.txt
+++ b/Documentation/git-shortlog.txt
@@ -76,6 +76,9 @@  them.
 Paths may need to be prefixed with `--` to separate them from
 options or the revision range, when confusion arises.

+:git-shortlog: 1
+include::rev-list-options.txt[]
+
 MAPPING AUTHORS
 ---------------

diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 90ff9e2bea..f4b67a917d 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -314,6 +314,7 @@  ifdef::git-rev-list[]
 	`<header>` text will be printed with each progress update.
 endif::git-rev-list[]

+ifndef::git-shortlog[]
 History Simplification
 ~~~~~~~~~~~~~~~~~~~~~~

@@ -1016,3 +1017,4 @@  options may be given. See linkgit:git-diff-files[1] for more options.
 -t::
 	Show the tree objects in the diff output. This implies `-r`.
 endif::git-rev-list[]
+endif::git-shortlog[]