{"thread":{"id":"52164","subject":"[PATCH] git-shortlog.txt: mention commit filtering options","startedAt":"2019-10-30T20:36:09Z","lastAt":"2019-11-08T19:26:33Z","messageCount":7,"participants":["Pratyush Yadav","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"385178","messageId":"20191030203603.27497-1-me@yadavpratyush.com","threadId":"52164","inReplyTo":null,"subject":"[PATCH] git-shortlog.txt: mention commit filtering options","fromName":"Pratyush Yadav","fromEmail":"me@yadavpratyush.com","sentAt":"2019-10-30T20:36:03Z","receivedAt":"2019-10-30T20:36:09Z","isPatch":true,"sender":{"key":"me@yadavpratyush.com","avatar":"https://avatars.githubusercontent.com/u/8817931?v=4"},"body":"git-shortlog, like git-log, supports options to filter what commits are\nused to generate the log. These options come from git-rev-list. Add a\npointer to these options in the documentation page so readers can know\nthese filtering options can be used with git-shortlog too.\n\nSigned-off-by: Pratyush Yadav <me@yadavpratyush.com>\n---\nSince [0] didn't get any responses, I figured a patch might get some\nmore attention since it is something concrete to comment on.\n\n[0] https://public-inbox.org/git/20191024191709.gqkjljuibyashtma@yadavpratyush.com/\n\n Documentation/git-shortlog.txt | 5 +++++\n 1 file changed, 5 insertions(+)\n\ndiff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt\nindex bc80905a8a..acae695388 100644\n--- a/Documentation/git-shortlog.txt\n+++ b/Documentation/git-shortlog.txt\n@@ -76,6 +76,11 @@ them.\n Paths may need to be prefixed with `--` to separate them from\n options or the revision range, when confusion arises.\n\n+In addition to the options above, 'git shortlog' also supports a range of\n+options to select which subset of commits will be used to generate the\n+shortlog. A list of these options can be found in the \"Commit Limiting\"\n+section of linkgit:git-rev-list[1].\n+\n MAPPING AUTHORS\n ---------------\n\n--\n2.21.0\n\n"},{"id":"385299","messageId":"xmqqftj64yv2.fsf@gitster-ct.c.googlers.com","threadId":"52164","inReplyTo":"20191030203603.27497-1-me@yadavpratyush.com","subject":"Re: [PATCH] git-shortlog.txt: mention commit filtering options","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-11-02T05:43:29Z","receivedAt":"2019-11-02T05:43:37Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Pratyush Yadav <me@yadavpratyush.com> writes:\n\n> git-shortlog, like git-log, supports options to filter what commits are\n> used to generate the log. These options come from git-rev-list. Add a\n> pointer to these options in the documentation page so readers can know\n> these filtering options can be used with git-shortlog too.\n>\n> Signed-off-by: Pratyush Yadav <me@yadavpratyush.com>\n> ---\n> Since [0] didn't get any responses, I figured a patch might get some\n> more attention since it is something concrete to comment on.\n>\n> [0] https://public-inbox.org/git/20191024191709.gqkjljuibyashtma@yadavpratyush.com/\n>\n>  Documentation/git-shortlog.txt | 5 +++++\n>  1 file changed, 5 insertions(+)\n>\n> diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt\n> index bc80905a8a..acae695388 100644\n> --- a/Documentation/git-shortlog.txt\n> +++ b/Documentation/git-shortlog.txt\n> @@ -76,6 +76,11 @@ them.\n>  Paths may need to be prefixed with `--` to separate them from\n>  options or the revision range, when confusion arises.\n>\n> +In addition to the options above, 'git shortlog' also supports a range of\n> +options to select which subset of commits will be used to generate the\n> +shortlog. A list of these options can be found in the \"Commit Limiting\"\n> +section of linkgit:git-rev-list[1].\n\nHow does \"git log --help\" handle the corresponding part of its\ndocumentation?  \n\n\t... goes and looks ...\n\nI wonder if it is better to just include rev-list-options.txt like\n\"git-log.txt\" does, instead of adding these four lines?\n\nThanks.\n\n>  MAPPING AUTHORS\n>  ---------------\n>\n> --\n> 2.21.0\n"},{"id":"385323","messageId":"20191102225045.zxxomy357zctxhfh@yadavpratyush.com","threadId":"52164","inReplyTo":"xmqqftj64yv2.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH] git-shortlog.txt: mention commit filtering options","fromName":"Pratyush Yadav","fromEmail":"me@yadavpratyush.com","sentAt":"2019-11-02T22:50:45Z","receivedAt":"2019-11-02T22:50:52Z","isPatch":true,"sender":{"key":"me@yadavpratyush.com","avatar":"https://avatars.githubusercontent.com/u/8817931?v=4"},"body":"On 02/11/19 02:43PM, Junio C Hamano wrote:\n> Pratyush Yadav <me@yadavpratyush.com> writes:\n> \n> > git-shortlog, like git-log, supports options to filter what commits are\n> > used to generate the log. These options come from git-rev-list. Add a\n> > pointer to these options in the documentation page so readers can know\n> > these filtering options can be used with git-shortlog too.\n> >\n> > Signed-off-by: Pratyush Yadav <me@yadavpratyush.com>\n> > ---\n> > Since [0] didn't get any responses, I figured a patch might get some\n> > more attention since it is something concrete to comment on.\n> >\n> > [0] https://public-inbox.org/git/20191024191709.gqkjljuibyashtma@yadavpratyush.com/\n> >\n> >  Documentation/git-shortlog.txt | 5 +++++\n> >  1 file changed, 5 insertions(+)\n> >\n> > diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt\n> > index bc80905a8a..acae695388 100644\n> > --- a/Documentation/git-shortlog.txt\n> > +++ b/Documentation/git-shortlog.txt\n> > @@ -76,6 +76,11 @@ them.\n> >  Paths may need to be prefixed with `--` to separate them from\n> >  options or the revision range, when confusion arises.\n> >\n> > +In addition to the options above, 'git shortlog' also supports a range of\n> > +options to select which subset of commits will be used to generate the\n> > +shortlog. A list of these options can be found in the \"Commit Limiting\"\n> > +section of linkgit:git-rev-list[1].\n> \n> How does \"git log --help\" handle the corresponding part of its\n> documentation?  \n> \n> \t... goes and looks ...\n> \n> I wonder if it is better to just include rev-list-options.txt like\n> \"git-log.txt\" does, instead of adding these four lines?\n\nQuoting from my initial email [0] about this topic:\n\n  rev-list-options.txt is a rather large file and I'm not sure if \n  including it in both git-log and git-shortlog would be a good idea. \n  The way I see it, git-log is the \"primary\" log interface, and \n  git-shortlog is a \"secondary\" log interface, so git-log warrants such \n  a large man page, but git-shortlog doesn't especially since most \n  options are repeated. So maybe it is a better idea to just include a \n  pointer to git-rev-list in the shortlog man page. \n\nBut if you think including the whole thing is better, I don't mind that \neither. Will re-roll.\n\n[0] https://public-inbox.org/git/20191024191709.gqkjljuibyashtma@yadavpratyush.com/\n\n-- \nRegards,\nPratyush Yadav\n"},{"id":"385358","messageId":"xmqq7e4g1fcw.fsf@gitster-ct.c.googlers.com","threadId":"52164","inReplyTo":"20191102225045.zxxomy357zctxhfh@yadavpratyush.com","subject":"Re: [PATCH] git-shortlog.txt: mention commit filtering options","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-11-04T03:37:35Z","receivedAt":"2019-11-04T03:37:46Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Pratyush Yadav <me@yadavpratyush.com> writes:\n\n>> How does \"git log --help\" handle the corresponding part of its\n>> documentation?  \n>> \n>> \t... goes and looks ...\n>> \n>> I wonder if it is better to just include rev-list-options.txt like\n>> \"git-log.txt\" does, instead of adding these four lines?\n>\n> Quoting from my initial email [0] about this topic:\n>\n>   rev-list-options.txt is a rather large file and I'm not sure if \n>   including it in both git-log and git-shortlog would be a good idea. \n>   The way I see it, git-log is the \"primary\" log interface, and \n>   git-shortlog is a \"secondary\" log interface, so git-log warrants such \n>   a large man page, but git-shortlog doesn't especially since most \n>   options are repeated. So maybe it is a better idea to just include a \n>   pointer to git-rev-list in the shortlog man page. \n\nOK, so you also wondered the same thing and reached a different\nconclusion.\n\nGiven that\n\n - \"rev-list-options\" being large is more or less irrelevant, if you\n   want to give users of \"short-log\" an easy access to these rich\n   options.  We already do so for users of \"log\".\n\n - \"include\" files are designed to reduce readers' mental load by\n   avoding one level of indirection and also to reduce the risk of\n   documentaiton going stale by avoiding repeated text in multiple\n   places, and that\n\n - if description in parts of included file only applies to one\n   including file but not others, ifdef/ifndef mechanism can be used\n   to customize the contents (see how rev-list-options.txt is\n   included in pages for both \"log\" and \"rev-list\", and parts of it\n   are shown conditionally with \"ifndef::git-rev-list[]\" and\n   friends; diff-options.txt and its users give you more examples to\n   follow).\n\nit is not such a bad idea to include the rev-list-options.txt.\n\nMore importantly, having a pointer to git-rev-list page may omit\nwhat is available to users of \"shortlog\" (options described inside\n\"ifndef::git-rev-list[]\" in rev-list-options.txt are not visible to\nthem) and/or describe what is not available to users of \"shortlog\"\n(those described inside \"ifdef::git-rev-list[]\" may not in general\napply to the \"log\" family of commands).\n\nThanks.\n"},{"id":"385391","messageId":"20191104130858.23673-1-me@yadavpratyush.com","threadId":"52164","inReplyTo":"20191030203603.27497-1-me@yadavpratyush.com","subject":"[PATCH v2] git-shortlog.txt: include commit limiting options","fromName":"Pratyush Yadav","fromEmail":"me@yadavpratyush.com","sentAt":"2019-11-04T13:08:58Z","receivedAt":"2019-11-04T13:09:05Z","isPatch":true,"sender":{"key":"me@yadavpratyush.com","avatar":"https://avatars.githubusercontent.com/u/8817931?v=4"},"body":"git-shortlog, like git-log, supports options to filter what commits are\nused to generate the log. These options come from git-rev-list, and are\ndocumented in Documentation/rev-list-options.txt. Include those options\nin shortlog's documentation.\n\nBut since rev-list-options.txt contains some other options that don't\nreally apply in the context of shortlog (like diff formatting, commit\nordering, etc), add a switch in rev-list-options.txt that excludes those\nsections from the shortlog documentation. To be more specific, include\nonly the \"Commit Limiting\" section.\n\nSigned-off-by: Pratyush Yadav <me@yadavpratyush.com>\n---\nThat ifdef covers almost the entire document. Is there a better way in\nAsciidoc to do something like this?\n\n Documentation/git-shortlog.txt     | 3 +++\n Documentation/rev-list-options.txt | 2 ++\n 2 files changed, 5 insertions(+)\n\ndiff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt\nindex bc80905a8a..a72ea7f7ba 100644\n--- a/Documentation/git-shortlog.txt\n+++ b/Documentation/git-shortlog.txt\n@@ -76,6 +76,9 @@ them.\n Paths may need to be prefixed with `--` to separate them from\n options or the revision range, when confusion arises.\n\n+:git-shortlog: 1\n+include::rev-list-options.txt[]\n+\n MAPPING AUTHORS\n ---------------\n\ndiff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt\nindex 90ff9e2bea..f4b67a917d 100644\n--- a/Documentation/rev-list-options.txt\n+++ b/Documentation/rev-list-options.txt\n@@ -314,6 +314,7 @@ ifdef::git-rev-list[]\n \t`<header>` text will be printed with each progress update.\n endif::git-rev-list[]\n\n+ifndef::git-shortlog[]\n History Simplification\n ~~~~~~~~~~~~~~~~~~~~~~\n\n@@ -1016,3 +1017,4 @@ options may be given. See linkgit:git-diff-files[1] for more options.\n -t::\n \tShow the tree objects in the diff output. This implies `-r`.\n endif::git-rev-list[]\n+endif::git-shortlog[]\n--\n2.21.0\n\n"},{"id":"385502","messageId":"xmqqk18dyexx.fsf@gitster-ct.c.googlers.com","threadId":"52164","inReplyTo":"20191104130858.23673-1-me@yadavpratyush.com","subject":"Re: [PATCH v2] git-shortlog.txt: include commit limiting options","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-11-06T01:24:42Z","receivedAt":"2019-11-06T01:24:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Pratyush Yadav <me@yadavpratyush.com> writes:\n\n> But since rev-list-options.txt contains some other options that don't\n> really apply in the context of shortlog (like diff formatting, commit\n> ordering, etc), add a switch in rev-list-options.txt that excludes those\n> sections from the shortlog documentation. To be more specific, include\n> only the \"Commit Limiting\" section.\n\nI think this is much better than duplication, and we can improve it\nfurther with follow-up patches.\n\nMany options for history simplification are useful for shortlog.  I\nvery often use \"git shortlog -- cache.h\" myself (i.e. limiting to\nthe given pathspec).  I suspect most of the \"--dashed-options\"\nlisted there would make sense for some workflows, even though I do\nnot use them often enough with shortlog.  The only exception I can\nthink of that may not be useful at all for the purose of shortlog is\n\"--simplify-by-decoration\".\n\nI agree with the patch that all other sections (i.e. bisection\nhelper, commit ordering, object traversal, commit formatting and\ndiff formatting) make little sense to use with shortlog.\n\n> Signed-off-by: Pratyush Yadav <me@yadavpratyush.com>\n> ---\n> That ifdef covers almost the entire document. Is there a better way in\n> Asciidoc to do something like this?\n\nI would have excluded each section independently with \"Heh, this\npart is not needed for shortlog\"; that would make it less error\nprone against future shuffling of sections in the file.\n\nThanks.\n"},{"id":"385795","messageId":"20191108192627.19408-1-me@yadavpratyush.com","threadId":"52164","inReplyTo":"20191030203603.27497-1-me@yadavpratyush.com","subject":"[PATCH v3] git-shortlog.txt: include commit limiting options","fromName":"Pratyush Yadav","fromEmail":"me@yadavpratyush.com","sentAt":"2019-11-08T19:26:27Z","receivedAt":"2019-11-08T19:26:33Z","isPatch":true,"sender":{"key":"me@yadavpratyush.com","avatar":"https://avatars.githubusercontent.com/u/8817931?v=4"},"body":"git-shortlog, like git-log, supports options to filter what commits are\nused to generate the log. These options come from git-rev-list, and are\ndocumented in Documentation/rev-list-options.txt. Include those options\nin shortlog's documentation.\n\nBut since rev-list-options.txt contains some other options that don't\nreally apply in the context of shortlog (like diff formatting, commit\nordering, etc), add a switch in rev-list-options.txt that excludes those\nsections from the shortlog documentation. To be more specific, include\nonly the \"Commit Limiting\" and \"History Simplification\" sections.\n\nSigned-off-by: Pratyush Yadav <me@yadavpratyush.com>\n---\nChanges in v3:\n- Include the \"History Simplification\" section too.\n\n- Wrap each section in an ifdef individually to make it easier to move\n  them around later.\n\n Documentation/git-shortlog.txt     |  3 +++\n Documentation/rev-list-options.txt | 11 ++++++++++-\n 2 files changed, 13 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt\nindex bc80905a8a..a72ea7f7ba 100644\n--- a/Documentation/git-shortlog.txt\n+++ b/Documentation/git-shortlog.txt\n@@ -76,6 +76,9 @@ them.\n Paths may need to be prefixed with `--` to separate them from\n options or the revision range, when confusion arises.\n\n+:git-shortlog: 1\n+include::rev-list-options.txt[]\n+\n MAPPING AUTHORS\n ---------------\n\ndiff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt\nindex 90ff9e2bea..e37df921b5 100644\n--- a/Documentation/rev-list-options.txt\n+++ b/Documentation/rev-list-options.txt\n@@ -579,6 +579,7 @@ above) if (1) they are referenced by tags, or (2) they change the\n contents of the paths given on the command line.  All other\n commits are marked as TREESAME (subject to be simplified away).\n\n+ifndef::git-shortlog[]\n ifdef::git-rev-list[]\n Bisection Helpers\n ~~~~~~~~~~~~~~~~~\n@@ -634,8 +635,9 @@ This option can be used along with `--bisect-vars`, in this case,\n after all the sorted commit objects, there will be the same text as if\n `--bisect-vars` had been used alone.\n endif::git-rev-list[]\n+endif::git-shortlog[]\n\n-\n+ifndef::git-shortlog[]\n Commit Ordering\n ~~~~~~~~~~~~~~~\n\n@@ -677,7 +679,9 @@ together.\n \tOutput the commits chosen to be shown (see Commit Limiting\n \tsection above) in reverse order. Cannot be combined with\n \t`--walk-reflogs`.\n+endif::git-shortlog[]\n\n+ifndef::git-shortlog[]\n Object Traversal\n ~~~~~~~~~~~~~~~~\n\n@@ -817,7 +821,9 @@ endif::git-rev-list[]\n\n --do-walk::\n \tOverrides a previous `--no-walk`.\n+endif::git-shortlog[]\n\n+ifndef::git-shortlog[]\n Commit Formatting\n ~~~~~~~~~~~~~~~~~\n\n@@ -973,7 +979,9 @@ ifdef::git-rev-list[]\n \tcounts and print the count for equivalent commits separated\n \tby a tab.\n endif::git-rev-list[]\n+endif::git-shortlog[]\n\n+ifndef::git-shortlog[]\n ifndef::git-rev-list[]\n Diff Formatting\n ~~~~~~~~~~~~~~~\n@@ -1016,3 +1024,4 @@ options may be given. See linkgit:git-diff-files[1] for more options.\n -t::\n \tShow the tree objects in the diff output. This implies `-r`.\n endif::git-rev-list[]\n+endif::git-shortlog[]\n--\n2.21.0\n\n"}]}