Re: [PATCH v2] git-shortlog.txt: include commit limiting options

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

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.