| Message ID | 20191030203603.27497-1-me@yadavpratyush.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | git-shortlog.txt: mention commit filtering options | expand |
Pratyush Yadav <me@yadavpratyush.com> writes: > 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(+) > > diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt > index bc80905a8a..acae695388 100644 > --- a/Documentation/git-shortlog.txt > +++ b/Documentation/git-shortlog.txt > @@ -76,6 +76,11 @@ them. > Paths may need to be prefixed with `--` to separate them from > options or the revision range, when confusion arises. > > +In addition to the options above, 'git shortlog' also supports a range of > +options to select which subset of commits will be used to generate the > +shortlog. A list of these options can be found in the "Commit Limiting" > +section of linkgit:git-rev-list[1]. 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. > MAPPING AUTHORS > --------------- > > -- > 2.21.0
On 02/11/19 02:43PM, Junio C Hamano wrote: > Pratyush Yadav <me@yadavpratyush.com> writes: > > > 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(+) > > > > diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt > > index bc80905a8a..acae695388 100644 > > --- a/Documentation/git-shortlog.txt > > +++ b/Documentation/git-shortlog.txt > > @@ -76,6 +76,11 @@ them. > > Paths may need to be prefixed with `--` to separate them from > > options or the revision range, when confusion arises. > > > > +In addition to the options above, 'git shortlog' also supports a range of > > +options to select which subset of commits will be used to generate the > > +shortlog. A list of these options can be found in the "Commit Limiting" > > +section of linkgit:git-rev-list[1]. > > 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? 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: >> 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? > > 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. 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.
diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt index bc80905a8a..acae695388 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -76,6 +76,11 @@ them. Paths may need to be prefixed with `--` to separate them from options or the revision range, when confusion arises. +In addition to the options above, 'git shortlog' also supports a range of +options to select which subset of commits will be used to generate the +shortlog. A list of these options can be found in the "Commit Limiting" +section of linkgit:git-rev-list[1]. + MAPPING AUTHORS ---------------
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(+) -- 2.21.0