{"thread":{"id":"33559","subject":"[PATCH v2 0/7] Documentation/shortlog improvements","startedAt":"2013-04-21T08:50:45Z","lastAt":"2013-04-21T19:06:51Z","messageCount":10,"participants":["Ramkumar Ramachandra","Junio C Hamano"],"isPatch":true,"patchVersion":2,"patchTotal":7},"messages":[{"id":"214993","messageId":"1366534252-12099-1-git-send-email-artagnon@gmail.com","threadId":"33559","inReplyTo":null,"subject":"[PATCH v2 0/7] Documentation/shortlog improvements","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-21T08:50:45Z","receivedAt":"2013-04-21T08:50:45Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"In this round, I've incorporated suggestions made by Junio:\n\n[3/7] is entirely new.\n\n[4/7] and [5/7] together re-order and replace '..' with\n'', in contrast to a single patch which attempted to\nfix '..' in-place in the previous version.\n\n[6/7] uses \"the revision range\" instad of \"revisions\".\n\n[7/7] copies the latest text from git-log.txt, and doesn't attempt to\nadd rev-list-options.txt.\n\nThere's a parallel discussion going on about fixing the meaning of\n\"revision\", but this series is entirely unrelated to that.\n\nRamkumar Ramachandra (7):\n git-shortlog.txt: remove (-h|--help) from OPTIONS\n builtin/shortlog.c: make usage string consistent with log\n revisions.txt: clarify the .. and ... syntax\n git-log.txt: order OPTIONS properly; move ..\n git-log.txt: generalize ..\n git-log.txt: rewrite note on why \"--\" may be required\n git-shortlog.txt: make SYNOPSIS match log, update OPTIONS\n\n Documentation/git-log.txt | 22 ++++++++++++----------\n Documentation/git-shortlog.txt | 25 +++++++++++++++++++------\n Documentation/revisions.txt | 6 ++++--\n builtin/shortlog.c | 4 +---\n 4 files changed, 36 insertions(+), 21 deletions(-)\n\n-- \n1.8.2.1.501.gd2949c7\n"},{"id":"214994","messageId":"1366534252-12099-2-git-send-email-artagnon@gmail.com","threadId":"33559","inReplyTo":"1366534252-12099-1-git-send-email-artagnon@gmail.com","subject":"[PATCH 1/7] git-shortlog.txt: remove (-h|--help) from OPTIONS","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-21T08:50:46Z","receivedAt":"2013-04-21T08:50:46Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"To be consistent with the documentation of all the other commands,\nremove (-h|--help) from the OPTIONS section.\n\nSigned-off-by: Ramkumar Ramachandra \n---\n Documentation/git-shortlog.txt | 4 ----\n 1 file changed, 4 deletions(-)\n\ndiff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt\nindex c308e91..c7f7f51 100644\n--- a/Documentation/git-shortlog.txt\n+++ b/Documentation/git-shortlog.txt\n@@ -26,10 +26,6 @@ reference to the current repository.\n OPTIONS\n -------\n \n--h::\n---help::\n-\tPrint a short usage message and exit.\n-\n -n::\n --numbered::\n \tSort output according to the number of commits per author instead\n-- \n1.8.2.1.501.gd2949c7\n"},{"id":"214995","messageId":"1366534252-12099-3-git-send-email-artagnon@gmail.com","threadId":"33559","inReplyTo":"1366534252-12099-1-git-send-email-artagnon@gmail.com","subject":"[PATCH 2/7] builtin/shortlog.c: make usage string consistent with log","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-21T08:50:47Z","receivedAt":"2013-04-21T08:50:47Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"\"--\" is used to separate pathspecs from the rev specs, and not rev\nspecs from the options, as the shortlog_usage string currently\nindicates. In correcting this usage string, make it consistent with\nthe log_usage string.\n\nSigned-off-by: Ramkumar Ramachandra \n---\n builtin/shortlog.c | 4 +---\n 1 file changed, 1 insertion(+), 3 deletions(-)\n\ndiff --git a/builtin/shortlog.c b/builtin/shortlog.c\nindex 240bff3..a2f54f2 100644\n--- a/builtin/shortlog.c\n+++ b/builtin/shortlog.c\n@@ -10,9 +10,7 @@\n #include \"parse-options.h\"\n \n static char const * const shortlog_usage[] = {\n-\tN_(\"git shortlog [-n] [-s] [-e] [-w] [rev-opts] [--] [... ]\"),\n-\t\"\",\n-\tN_(\"[rev-opts] are documented in git-rev-list(1)\"),\n+\tN_(\"git shortlog [] [..] [[--] [...]]\"),\n \tNULL\n };\n \n-- \n1.8.2.1.501.gd2949c7\n"},{"id":"214996","messageId":"1366534252-12099-4-git-send-email-artagnon@gmail.com","threadId":"33559","inReplyTo":"1366534252-12099-1-git-send-email-artagnon@gmail.com","subject":"[PATCH 3/7] revisions.txt: clarify the .. and ... syntax","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-21T08:50:48Z","receivedAt":"2013-04-21T08:50:48Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"In .. and ..., if either or is\nomitted, it defaults to 'HEAD'. Add this detail to the document.\n\nSigned-off-by: Ramkumar Ramachandra \n---\n Documentation/revisions.txt | 6 ++++--\n 1 file changed, 4 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 8855b1a..0a23129 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -244,11 +244,13 @@ To summarize:\n \n '..'::\n \tInclude commits that are reachable from but exclude\n-\tthose that are reachable from .\n+\tthose that are reachable from . When either or\n+\t is omitted, it defaults to 'HEAD'.\n \n '\\...'::\n \tInclude commits that are reachable from either or\n-\t but exclude those that are reachable from both.\n+\t but exclude those that are reachable from both. When\n+\teither or is omitted, it defaults to 'HEAD'.\n \n '{caret}@', e.g. 'HEAD{caret}@'::\n A suffix '{caret}' followed by an at sign is the same as listing\n-- \n1.8.2.1.501.gd2949c7\n"},{"id":"214997","messageId":"1366534252-12099-5-git-send-email-artagnon@gmail.com","threadId":"33559","inReplyTo":"1366534252-12099-1-git-send-email-artagnon@gmail.com","subject":"[PATCH 4/7] git-log.txt: order OPTIONS properly; move ..","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-21T08:50:49Z","receivedAt":"2013-04-21T08:50:49Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"The OPTIONS section lists .. as the first item, but this\nis inconsistent with the ordering in SYNOPSIS. Move it down until it\nappears just before [[--] ...].\n\nSigned-off-by: Ramkumar Ramachandra \n---\n Documentation/git-log.txt | 14 +++++++-------\n 1 file changed, 7 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 69db578..64cc337 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -24,13 +24,6 @@ each commit introduces are shown.\n OPTIONS\n -------\n \n-..::\n-\tShow only commits between the named two commits. When\n-\teither or is omitted, it defaults to\n-\t`HEAD`, i.e. the tip of the current branch.\n-\tFor a more complete list of ways to spell \n-\tand , see linkgit:gitrevisions[7].\n-\n --follow::\n \tContinue listing the history of a file beyond renames\n \t(works only for a single file).\n@@ -69,6 +62,13 @@ produced by --stat etc.\n \tNote that only message is considered, if also a diff is shown\n \tits size is not included.\n \n+..::\n+\tShow only commits between the named two commits. When\n+\teither or is omitted, it defaults to\n+\t`HEAD`, i.e. the tip of the current branch.\n+\tFor a more complete list of ways to spell \n+\tand , see linkgit:gitrevisions[7].\n+\n [\\--] ...::\n \tShow only commits that are enough to explain how the files\n \tthat match the specified paths came to be. See \"History\n-- \n1.8.2.1.501.gd2949c7\n"},{"id":"214998","messageId":"1366534252-12099-6-git-send-email-artagnon@gmail.com","threadId":"33559","inReplyTo":"1366534252-12099-1-git-send-email-artagnon@gmail.com","subject":"[PATCH 5/7] git-log.txt: generalize ..","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-21T08:50:50Z","receivedAt":"2013-04-21T08:50:50Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"'..' is misleading, as there are many other forms that\n'git log' can accept as an argument. Replace it with ,\nreferring to the section \"Specifying Ranges\" in revisions.txt, and\nrewrite the section appropriately.\n\nSigned-off-by: Ramkumar Ramachandra \n---\n Documentation/git-log.txt | 16 +++++++++-------\n 1 file changed, 9 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 64cc337..c238475 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -9,7 +9,7 @@ git-log - Show commit logs\n SYNOPSIS\n --------\n [verse]\n-'git log' [] [..] [[\\--] ...]\n+'git log' [] [] [[\\--] ...]\n \n DESCRIPTION\n -----------\n@@ -62,12 +62,14 @@ produced by --stat etc.\n \tNote that only message is considered, if also a diff is shown\n \tits size is not included.\n \n-..::\n-\tShow only commits between the named two commits. When\n-\teither or is omitted, it defaults to\n-\t`HEAD`, i.e. the tip of the current branch.\n-\tFor a more complete list of ways to spell \n-\tand , see linkgit:gitrevisions[7].\n+::\n+\tShow only commits in the specified revision range. When no\n+\t is specified, it defaults to 'HEAD' (ie. the\n+\twhole history leading to the current commit). master..HEAD\n+\tspecifies all the commits reachable from 'HEAD', but not from\n+\t'master'. For a complete list of ways to spell\n+\t, see the \"Specifying Ranges\" section of\n+\tlinkgit:gitrevisions[7].\n \n [\\--] ...::\n \tShow only commits that are enough to explain how the files\n-- \n1.8.2.1.501.gd2949c7\n"},{"id":"214999","messageId":"1366534252-12099-7-git-send-email-artagnon@gmail.com","threadId":"33559","inReplyTo":"1366534252-12099-1-git-send-email-artagnon@gmail.com","subject":"[PATCH 6/7] git-log.txt: rewrite note on why \"--\" may be required","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-21T08:50:51Z","receivedAt":"2013-04-21T08:50:51Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"In its current form, the note talks about separating options from\n\"branch names\" and \"refnames\" in the same sentence. This is entirely\ninaccurate, as need not be a set of branch names or\nref names. Rewrite it to use the word \"revision range\", to be\nconsistent with the SYNOPSIS.\n\nSigned-off-by: Ramkumar Ramachandra \n---\n Documentation/git-log.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex c238475..7ae21ff 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -77,8 +77,8 @@ produced by --stat etc.\n \tSimplification\" below for details and other simplification\n \tmodes.\n +\n-To prevent confusion with options and branch names, paths may need to\n-be prefixed with \"\\-- \" to separate them from options or refnames.\n+Paths may need to be prefixed with \"\\-- \" to separate them from\n+options or the revision range, when confusion arises.\n \n include::rev-list-options.txt[]\n \n-- \n1.8.2.1.501.gd2949c7\n"},{"id":"215000","messageId":"1366534252-12099-8-git-send-email-artagnon@gmail.com","threadId":"33559","inReplyTo":"1366534252-12099-1-git-send-email-artagnon@gmail.com","subject":"[PATCH 7/7] git-shortlog.txt: make SYNOPSIS match log, update OPTIONS","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-21T08:50:52Z","receivedAt":"2013-04-21T08:50:52Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"There are broadly two problems with the current SYNOPSIS. First, it\ncompletely omits the detail that paths can be specified. Second, it\nattempts to list all the options: this is futile as, in addition to\nthe options unique to it, it accepts all the options that git-rev-list\naccepts. In fixing these problems, make the SYNOPSIS consistent with\nthat in git-log.txt. Also add the corresponding sections to OPTIONS.\nSave adding the options from rev-list-options.txt for a later patch,\nas it requires some work to pick out the options that are relevant to\nshortlog.\n\nSigned-off-by: Ramkumar Ramachandra \n---\n Documentation/git-shortlog.txt | 21 +++++++++++++++++++--\n 1 file changed, 19 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt\nindex c7f7f51..2a66518 100644\n--- a/Documentation/git-shortlog.txt\n+++ b/Documentation/git-shortlog.txt\n@@ -8,8 +8,8 @@ git-shortlog - Summarize 'git log' output\n SYNOPSIS\n --------\n [verse]\n-git log --pretty=short | 'git shortlog' [-h] [-n] [-s] [-e] [-w]\n-'git shortlog' [-n|--numbered] [-s|--summary] [-e|--email] [-w[[,[,]]]] ...\n+git log --pretty=short | 'git shortlog' []\n+'git shortlog' [] [] [[\\--] ...]\n \n DESCRIPTION\n -----------\n@@ -56,6 +56,23 @@ OPTIONS\n If width is `0` (zero) then indent the lines of the output without wrapping\n them.\n \n+::\n+\tConsider only commits in the specified revision range. When no\n+\t is specified, it defaults to 'HEAD' (ie. the\n+\twhole history leading to the current commit). master..next\n+\tspecifies all the commits reachable from 'next, but not from\n+\t'master'. For a complete list of ways to spell\n+\t, see the \"Specifying Ranges\" section of\n+\tlinkgit:gitrevisions[7].\n+\n+[\\--] ...::\n+\tConsider only commits that are enough to explain how the files\n+\tthat match the specified paths came to be. See \"History\n+\tSimplification\" below for details and other simplification\n+\tmodes.\n++\n+Paths may need to be prefixed with \"\\-- \" to separate them from\n+options or the revision range, when confusion arises.\n \n MAPPING AUTHORS\n ---------------\n-- \n1.8.2.1.501.gd2949c7\n"},{"id":"215027","messageId":"7va9oru32u.fsf@alter.siamese.dyndns.org","threadId":"33559","inReplyTo":"1366534252-12099-6-git-send-email-artagnon@gmail.com","subject":"Re: [PATCH 5/7] git-log.txt: generalize ..","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-04-21T18:54:33Z","receivedAt":"2013-04-21T18:54:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ramkumar Ramachandra writes:\n\n> '..' is misleading, as there are many other forms that\n> 'git log' can accept as an argument. Replace it with ,\n> referring to the section \"Specifying Ranges\" in revisions.txt, and\n> rewrite the section appropriately.\n>\n> Signed-off-by: Ramkumar Ramachandra \n> ---\n> Documentation/git-log.txt | 16 +++++++++-------\n> 1 file changed, 9 insertions(+), 7 deletions(-)\n>\n> diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\n> index 64cc337..c238475 100644\n> --- a/Documentation/git-log.txt\n> +++ b/Documentation/git-log.txt\n> @@ -9,7 +9,7 @@ git-log - Show commit logs\n> SYNOPSIS\n> --------\n> [verse]\n> -'git log' [] [..] [[\\--] ...]\n> +'git log' [] [] [[\\--] ...]\n> \n> DESCRIPTION\n> -----------\n> @@ -62,12 +62,14 @@ produced by --stat etc.\n> \tNote that only message is considered, if also a diff is shown\n> \tits size is not included.\n> \n> -..::\n> -\tShow only commits between the named two commits. When\n> -\teither or is omitted, it defaults to\n> -\t`HEAD`, i.e. the tip of the current branch.\n> -\tFor a more complete list of ways to spell \n> -\tand , see linkgit:gitrevisions[7].\n> +::\n> +\tShow only commits in the specified revision range. When no\n> +\t is specified, it defaults to 'HEAD' (ie. the\n\ns/ie/i.e./; or s/ie/meaning /;\n\n> +\twhole history leading to the current commit). master..HEAD\n> +\tspecifies all the commits reachable from 'HEAD', but not from\n> +\t'master'. For a complete list of ways to spell\n> +\t, see the \"Specifying Ranges\" section of\n> +\tlinkgit:gitrevisions[7].\n\nIf you want to have a single example (other than 'HEAD' which has to\nbe there anyway to describe the default), I think it would be more\nhelpful to use one that would be common for not-so-advanced users,\ne.g. \"origin..HEAD\", without many other prerequisites (e.g. \"@{u}..\"\nmay be common among more advanced users but is not appropriate here,\nbecause the reader may not have learned @{upstream} or omission of a\nside of a range defaulting to HEAD).\n\n\t... `origin..HEAD` specifies all the commits reachable from\n\tthe current commit (i.e. `HEAD`) but not from `origin`.\n\nI could squash these in locally without a reroll, but I haven't read\nthe remainder of the series yet, so we'll see.\n\n> [\\--] ...::\n> \tShow only commits that are enough to explain how the files\n"},{"id":"215030","messageId":"7vip3fsnxw.fsf@alter.siamese.dyndns.org","threadId":"33559","inReplyTo":"1366534252-12099-8-git-send-email-artagnon@gmail.com","subject":"Re: [PATCH 7/7] git-shortlog.txt: make SYNOPSIS match log, update OPTIONS","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-04-21T19:06:51Z","receivedAt":"2013-04-21T19:06:51Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ramkumar Ramachandra writes:\n\n> diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt\n> index c7f7f51..2a66518 100644\n> --- a/Documentation/git-shortlog.txt\n> +++ b/Documentation/git-shortlog.txt\n> @@ -8,8 +8,8 @@ git-shortlog - Summarize 'git log' output\n> SYNOPSIS\n> --------\n> [verse]\n> -git log --pretty=short | 'git shortlog' [-h] [-n] [-s] [-e] [-w]\n> -'git shortlog' [-n|--numbered] [-s|--summary] [-e|--email] [-w[[,[,]]]] ...\n> +git log --pretty=short | 'git shortlog' []\n> +'git shortlog' [] [] [[\\--] ...]\n\nYou will need to update what you added in [PATCH 2/7] to\nbuiltin/shortlog.c to match this in this patch.\n\n> DESCRIPTION\n> -----------\n> @@ -56,6 +56,23 @@ OPTIONS\n> If width is `0` (zero) then indent the lines of the output without wrapping\n> them.\n> \n> +::\n> +\tConsider only commits in the specified revision range. When no\n> +\t is specified, it defaults to 'HEAD' (ie. the\n> +\twhole history leading to the current commit). master..next\n> +\tspecifies all the commits reachable from 'next, but not from\n> +\t'master'. For a complete list of ways to spell\n> +\t, see the \"Specifying Ranges\" section of\n> +\tlinkgit:gitrevisions[7].\n\nMatch the text you modified in 'log.txt' in [PATCH 5/7], perhaps?\n\n> +[\\--] ...::\n> +\tConsider only commits that are enough to explain how the files\n> +\tthat match the specified paths came to be. See \"History\n> +\tSimplification\" below for details and other simplification\n> +\tmodes.\n\nHave you read the resulting \"git shortlog --help\"? Do we even have\n\"below\"?\n\n> ++\n> +Paths may need to be prefixed with \"\\-- \" to separate them from\n> +options or the revision range, when confusion arises.\n> \n> MAPPING AUTHORS\n> ---------------\n"}]}