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

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 6, 2019, 01:24 UTC
Message-ID: <xmqqk18dyexx.fsf@gitster-ct.c.googlers.com>
In-Reply-To: <20191104130858.23673-1-me@yadavpratyush.com>

Pratyush Yadav <me@yadavpratyush.com> writes:

Show 5 quoted lines

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