patchgit-shortlog.txt: mention commit filtering options

git-shortlog, like git-log, supports options to filter what commits are used to generate the log. These options come from git-rev-list. Add a pointer to these options in the documentation page so readers can know these filtering options can be used with git-shortlog too.

Signed-off-by: Pratyush Yadav <me@yadavpratyush.com>
---
Since [0] didn't get any responses, I figured a patch might get some
more attention since it is something concrete to comment on.

[0] https://public-inbox.org/git/20191024191709.gqkjljuibyashtma@yadavpratyush.com/

 Documentation/git-shortlog.txt | 5 +++++
 1 file changed, 5 insertions(+)

Pratyush Yadav <me@yadavpratyush.com> writes:

How does "git log --help" handle the corresponding part of its documentation?

	... goes and looks ...

I wonder if it is better to just include rev-list-options.txt like "git-log.txt" does, instead of adding these four lines?

Thanks.

On 02/11/19 02:43PM, Junio C Hamano wrote:

Quoting from my initial email [0] about this topic:

  rev-list-options.txt is a rather large file and I'm not sure if 
  including it in both git-log and git-shortlog would be a good idea. 
  The way I see it, git-log is the "primary" log interface, and 
  git-shortlog is a "secondary" log interface, so git-log warrants such 
  a large man page, but git-shortlog doesn't especially since most 
  options are repeated. So maybe it is a better idea to just include a 
  pointer to git-rev-list in the shortlog man page. 

But if you think including the whole thing is better, I don't mind that either. Will re-roll.

[0] https://public-inbox.org/git/20191024191709.gqkjljuibyashtma@yadavpratyush.com/

Pratyush Yadav <me@yadavpratyush.com> writes:

OK, so you also wondered the same thing and reached a different conclusion.

Given that

 - "rev-list-options" being large is more or less irrelevant, if you
   want to give users of "short-log" an easy access to these rich
   options.  We already do so for users of "log".

 - "include" files are designed to reduce readers' mental load by
   avoding one level of indirection and also to reduce the risk of
   documentaiton going stale by avoiding repeated text in multiple
   places, and that

 - if description in parts of included file only applies to one
   including file but not others, ifdef/ifndef mechanism can be used
   to customize the contents (see how rev-list-options.txt is
   included in pages for both "log" and "rev-list", and parts of it
   are shown conditionally with "ifndef::git-rev-list[]" and
   friends; diff-options.txt and its users give you more examples to
   follow).

it is not such a bad idea to include the rev-list-options.txt.

More importantly, having a pointer to git-rev-list page may omit what is available to users of "shortlog" (options described inside "ifndef::git-rev-list[]" in rev-list-options.txt are not visible to them) and/or describe what is not available to users of "shortlog" (those described inside "ifdef::git-rev-list[]" may not in general apply to the "log" family of commands).

Thanks.

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(+)

Pratyush Yadav <me@yadavpratyush.com> writes:

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.

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.

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" and "History Simplification" sections.

Signed-off-by: Pratyush Yadav <me@yadavpratyush.com>
---
Changes in v3:
- Include the "History Simplification" section too.

- Wrap each section in an ifdef individually to make it easier to move
  them around later.

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