{"thread":{"id":"33565","subject":"[PATCH v3 0/7] Documentation/shortlog improvements","startedAt":"2013-04-22T05:30:24Z","lastAt":"2013-04-29T17:38:56Z","messageCount":13,"participants":["Ramkumar Ramachandra","Junio C Hamano"],"isPatch":true,"patchVersion":3,"patchTotal":7},"messages":[{"id":"215052","messageId":"1366608631-21734-1-git-send-email-artagnon@gmail.com","threadId":"33565","inReplyTo":null,"subject":"[PATCH v3 0/7] Documentation/shortlog improvements","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-22T05:30:24Z","receivedAt":"2013-04-22T05:30:24Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Hi,\n\nThe re-roll was necessary due to minor/silly mistakes in v2, as\npointed out by Junio.\n\nThe builtin/shortlog.c patch has moved to the end until we change\n'<since>..<until>' to '<revision range>' everywhere else.  We use\n'<revision range>' here too.\n\n[4/7] has been replaced with the version Junio fixed up and put in\n`pu`.\n\n[6/7] has been updated to copy sections from log.txt properly, and\nomit the \"see below for History Simplification\" part.\n\nThanks.\n\nRamkumar Ramachandra (7):\n  git-shortlog.txt: remove (-h|--help) from OPTIONS\n  revisions.txt: clarify the .. and ... syntax\n  git-log.txt: order OPTIONS properly; move <since>..<until>\n  git-log.txt: generalize <since>..<until>\n  git-log.txt: rewrite note on why \"--\" may be required\n  git-shortlog.txt: make SYNOPSIS match log, update OPTIONS\n  builtin/shortlog.c: make usage string consistent with log\n\n Documentation/git-log.txt      | 22 ++++++++++++----------\n Documentation/git-shortlog.txt | 23 +++++++++++++++++------\n Documentation/revisions.txt    |  6 ++++--\n builtin/shortlog.c             |  4 +---\n 4 files changed, 34 insertions(+), 21 deletions(-)\n\n-- \n1.8.2.1.501.gd2949c7\n"},{"id":"215055","messageId":"1366608631-21734-2-git-send-email-artagnon@gmail.com","threadId":"33565","inReplyTo":"1366608631-21734-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-22T05:30:25Z","receivedAt":"2013-04-22T05:30:25Z","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 <artagnon@gmail.com>\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":"215057","messageId":"1366608631-21734-3-git-send-email-artagnon@gmail.com","threadId":"33565","inReplyTo":"1366608631-21734-1-git-send-email-artagnon@gmail.com","subject":"[PATCH 2/7] revisions.txt: clarify the .. and ... syntax","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-22T05:30:26Z","receivedAt":"2013-04-22T05:30:26Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"In <rev1>..<rev2> and <rev1>...<rev2>, if either <rev1> or <rev2> is\nomitted, it defaults to 'HEAD'.  Add this detail to the document.\n\nSigned-off-by: Ramkumar Ramachandra <artagnon@gmail.com>\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 '<rev1>..<rev2>'::\n \tInclude commits that are reachable from <rev2> but exclude\n-\tthose that are reachable from <rev1>.\n+\tthose that are reachable from <rev1>.  When either <rev1> or\n+\t<rev2> is omitted, it defaults to 'HEAD'.\n \n '<rev1>\\...<rev2>'::\n \tInclude commits that are reachable from either <rev1> or\n-\t<rev2> but exclude those that are reachable from both.\n+\t<rev2> but exclude those that are reachable from both.  When\n+\teither <rev1> or <rev2> is omitted, it defaults to 'HEAD'.\n \n '<rev>{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":"215056","messageId":"1366608631-21734-4-git-send-email-artagnon@gmail.com","threadId":"33565","inReplyTo":"1366608631-21734-1-git-send-email-artagnon@gmail.com","subject":"[PATCH 3/7] git-log.txt: order OPTIONS properly; move <since>..<until>","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-22T05:30:27Z","receivedAt":"2013-04-22T05:30:27Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"The OPTIONS section lists <since>..<until> as the first item, but this\nis inconsistent with the ordering in SYNOPSIS.  Move it down until it\nappears just before [[--] <path>...].\n\nSigned-off-by: Ramkumar Ramachandra <artagnon@gmail.com>\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-<since>..<until>::\n-\tShow only commits between the named two commits.  When\n-\teither <since> or <until> 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 <since>\n-\tand <until>, 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+<since>..<until>::\n+\tShow only commits between the named two commits.  When\n+\teither <since> or <until> 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 <since>\n+\tand <until>, see linkgit:gitrevisions[7].\n+\n [\\--] <path>...::\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":"215054","messageId":"1366608631-21734-5-git-send-email-artagnon@gmail.com","threadId":"33565","inReplyTo":"1366608631-21734-1-git-send-email-artagnon@gmail.com","subject":"[PATCH 4/7] git-log.txt: generalize <since>..<until>","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-22T05:30:28Z","receivedAt":"2013-04-22T05:30:28Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"'<since>..<until>' is misleading, as there are many other forms that\n'git log' can accept as an argument.  Replace it with <revision range>,\nreferring to the section \"Specifying Ranges\" in revisions.txt, and\nrewrite the section appropriately.\n\nSigned-off-by: Ramkumar Ramachandra <artagnon@gmail.com>\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..9576695 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' [<options>] [<since>..<until>] [[\\--] <path>...]\n+'git log' [<options>] [<revision range>] [[\\--] <path>...]\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-<since>..<until>::\n-\tShow only commits between the named two commits.  When\n-\teither <since> or <until> 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 <since>\n-\tand <until>, see linkgit:gitrevisions[7].\n+<revision range>::\n+\tShow only commits in the specified revision range.  When no\n+\t<revision range> is specified, it defaults to `HEAD` (i.e. the\n+\twhole history leading to the current commit).  `origin..HEAD`\n+\tspecifies all the commits reachable from the current commit\n+\t(i.e. `HEAD`), but not from `origin`. For a complete list of\n+\tways to spell <revision range>, see the \"Specifying Ranges\"\n+\tsection of linkgit:gitrevisions[7].\n \n [\\--] <path>...::\n \tShow only commits that are enough to explain how the files\n-- \n1.8.2.1.501.gd2949c7\n"},{"id":"215053","messageId":"1366608631-21734-6-git-send-email-artagnon@gmail.com","threadId":"33565","inReplyTo":"1366608631-21734-1-git-send-email-artagnon@gmail.com","subject":"[PATCH 5/7] git-log.txt: rewrite note on why \"--\" may be required","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-22T05:30:29Z","receivedAt":"2013-04-22T05:30:29Z","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 <revision range> 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 <artagnon@gmail.com>\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 9576695..a976534 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":"215058","messageId":"1366608631-21734-7-git-send-email-artagnon@gmail.com","threadId":"33565","inReplyTo":"1366608631-21734-1-git-send-email-artagnon@gmail.com","subject":"[PATCH 6/7] git-shortlog.txt: make SYNOPSIS match log, update OPTIONS","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-22T05:30:30Z","receivedAt":"2013-04-22T05:30:30Z","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 <artagnon@gmail.com>\n---\n Documentation/git-shortlog.txt | 19 +++++++++++++++++--\n 1 file changed, 17 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt\nindex c7f7f51..31af7f2 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[<width>[,<indent1>[,<indent2>]]]] <commit>...\n+git log --pretty=short | 'git shortlog' [<options>]\n+'git shortlog' [<options>] [<revision range>] [[\\--] <path>...]\n \n DESCRIPTION\n -----------\n@@ -56,6 +56,21 @@ OPTIONS\n If width is `0` (zero) then indent the lines of the output without wrapping\n them.\n \n+<revision range>::\n+\tShow only commits in the specified revision range.  When no\n+\t<revision range> is specified, it defaults to `HEAD` (i.e. the\n+\twhole history leading to the current commit).  `origin..HEAD`\n+\tspecifies all the commits reachable from the current commit\n+\t(i.e. `HEAD`), but not from `origin`. For a complete list of\n+\tways to spell <revision range>, see the \"Specifying Ranges\"\n+\tsection of linkgit:gitrevisions[7].\n+\n+[\\--] <path>...::\n+\tConsider only commits that are enough to explain how the files\n+\tthat match the specified paths came to be.\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":"215059","messageId":"1366608631-21734-8-git-send-email-artagnon@gmail.com","threadId":"33565","inReplyTo":"1366608631-21734-1-git-send-email-artagnon@gmail.com","subject":"[PATCH 7/7] builtin/shortlog.c: make usage string consistent with log","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-22T05:30:31Z","receivedAt":"2013-04-22T05:30:31Z","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 <artagnon@gmail.com>\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..1fd6f8a 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] [--] [<commit-id>... ]\"),\n-\t\"\",\n-\tN_(\"[rev-opts] are documented in git-rev-list(1)\"),\n+\tN_(\"git shortlog [<options>] [<revision range>] [[--] [<path>...]]\"),\n \tNULL\n };\n \n-- \n1.8.2.1.501.gd2949c7\n"},{"id":"215061","messageId":"1366615244-21825-1-git-send-email-artagnon@gmail.com","threadId":"33565","inReplyTo":"1366608631-21734-8-git-send-email-artagnon@gmail.com","subject":"[PATCH 6.5/7] builtin/log.c: make usage string consistent with doc","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-22T07:20:44Z","receivedAt":"2013-04-22T07:20:44Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Replace '<since>..<until>' with '<revision range>', in accordance with\nthe documentation.\n\nSigned-off-by: Ramkumar Ramachandra <artagnon@gmail.com>\n---\n Junio: sorry I missed this detail.  Can you squeeze this patch\n between [6/7] and [7/7] so that the commit message in [7/7] makes\n sense?\n\n Thanks.\n\n builtin/log.c | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/builtin/log.c b/builtin/log.c\nindex ad46f72..6e56a50 100644\n--- a/builtin/log.c\n+++ b/builtin/log.c\n@@ -37,7 +37,7 @@ static const char *fmt_patch_subject_prefix = \"PATCH\";\n static const char *fmt_pretty;\n \n static const char * const builtin_log_usage[] = {\n-\tN_(\"git log [<options>] [<since>..<until>] [[--] <path>...]\\n\")\n+\tN_(\"git log [<options>] [<revision range>] [[--] <path>...]\\n\")\n \tN_(\"   or: git show [options] <object>...\"),\n \tNULL\n };\n-- \n1.8.2.1.423.g9a53c75.dirty\n"},{"id":"215399","messageId":"7vmwsn8ok4.fsf_-_@alter.siamese.dyndns.org","threadId":"33565","inReplyTo":"1366608631-21734-6-git-send-email-artagnon@gmail.com","subject":"Re* [PATCH 5/7] git-log.txt: rewrite note on why \"--\" may be required","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-04-25T00:02:51Z","receivedAt":"2013-04-25T00:02:51Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ramkumar Ramachandra <artagnon@gmail.com> writes:\n\n> In its current form, the note talks about separating options from\n> \"branch names\" and \"refnames\" in the same sentence.  This is entirely\n> inaccurate, as <revision range> need not be a set of branch names or\n> ref names.  Rewrite it to use the word \"revision range\", to be\n> consistent with the SYNOPSIS.\n>\n> Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>\n> ---\n>  Documentation/git-log.txt | 4 ++--\n>  1 file changed, 2 insertions(+), 2 deletions(-)\n>\n> diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\n> index 9576695..a976534 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\nThis is an explanation about an enumeration item:\n\n\t[\\--] <path>...::\n\nwhich corresponds to this in the synopsis:\n\n        'git log' [<options>] [<revision range>] [[\\--] <path>...]\n\nBut the synopsis looks incorrect to me.  It insists that if you were\nto write \"--\", you have to give at least one <path>.\n\nIt should be more like this [*1*]:\n\n\t'git log' [<options>] [<revision range>] [--] [<path>...]\n\nIt may be better to split the item into two, keep the current\ndescription of <path> under \"<path>...::\" heading, and have another\nheading for \"--::\" that talks about the disambiguation.  The \"--\"\ndisambiguator is not solely for \"your path might be mistaken as a\nrevision without it\", but also for \"your revision might be mistaken\nas a path\", but both the old and the new text are fuzzy about the\nreason what \"confusion\" it is cautioning the reader.\n\nFormatting doubts aside, one thing I am not so happy about the\nsuggested patch below (would apply on top of the patches from this\nseries) is that the explanation of a double-dash requires\nunderstanding of _both_ what <revision range> and <path>... means to\nthe command, but for a reader who has read this page from top, the\nlatter has not been explained yet.  We could of course swap the\norder and describe <path>... first and then \"--\", but that does not\nsound quite right, either.  It has to be between these two.\n\n\n[Footnote]\n\n*1* We have many instances like \"[--quiet]\" in Documentation; do we\n    need the backslash before these double-dash like \"[\\--]\"?\n\n\n Documentation/git-log.txt | 22 +++++++++++++++++-----\n 1 file changed, 17 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex a976534..f5746e4 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' [<options>] [<revision range>] [[\\--] <path>...]\n+'git log' [<options>] [<revision range>] [--] [<path>...]\n \n DESCRIPTION\n -----------\n@@ -71,14 +71,26 @@ produced by --stat etc.\n \tways to spell <revision range>, see the \"Specifying Ranges\"\n \tsection of linkgit:gitrevisions[7].\n \n-[\\--] <path>...::\n+--::\n+\tOn the command line, arguments that specify revision range\n+\tcome first and then paths (see the next item).  A\n+\tdouble-dash can be used to mark the end of revision range\n+\targuments when an argument can be otherwise ambiguous.\n++\n+For example, when there are a file called `master` and a branch with\n+the same name, what `git log master` means is unclear.  It may be\n+asking for the whole history leading to the current commit (i.e. no\n+<revision range> is specified, defaulting to `HEAD`), limited to\n+commits that touch a single path `master`.  Or it may be asking for\n+the whole history leading to the tip of `master`, without any path\n+limiting.  The former can be spelled `git log -- master`, while the\n+latter can be spelled `git log master --`.\n+\n+<path>...::\n \tShow 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 include::rev-list-options.txt[]\n \n"},{"id":"215404","messageId":"CALkWK0m2__SZmpyQqLjkJuMWtPuD4=Oo7QrYovq_Fw6fpHEXXQ@mail.gmail.com","threadId":"33565","inReplyTo":"7vmwsn8ok4.fsf_-_@alter.siamese.dyndns.org","subject":"Re: Re* [PATCH 5/7] git-log.txt: rewrite note on why \"--\" may be required","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-25T05:17:25Z","receivedAt":"2013-04-25T05:17:25Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Junio C Hamano wrote:\n> It should be more like this [*1*]:\n>\n>         'git log' [<options>] [<revision range>] [--] [<path>...]\n\nAgreed.  The backslash is unnecessary (I suspect it's something\ncarried over from earlier versions of asciidoc requiring this\nescaping).\n\n> It may be better to split the item into two, keep the current\n> description of <path> under \"<path>...::\" heading, and have another\n> heading for \"--::\" that talks about the disambiguation.  The \"--\"\n> disambiguator is not solely for \"your path might be mistaken as a\n> revision without it\", but also for \"your revision might be mistaken\n> as a path\", but both the old and the new text are fuzzy about the\n> reason what \"confusion\" it is cautioning the reader.\n\nI agree that the \"confusion\" paragraph after [--] [<path>] can be\nimproved, but putting [--] in a paragraph of its own sounds like an\noverkill.  Apart from other things, it means that every single git\ncommand would need an identical [--] paragraph for consistency.  We\ncan just keep the footnote following [--] [<path>] in some commands,\nusing discretion.\n"},{"id":"215866","messageId":"7va9ohl2k7.fsf@alter.siamese.dyndns.org","threadId":"33565","inReplyTo":"CALkWK0m2__SZmpyQqLjkJuMWtPuD4=Oo7QrYovq_Fw6fpHEXXQ@mail.gmail.com","subject":"Re: Re* [PATCH 5/7] git-log.txt: rewrite note on why \"--\" may be required","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-04-29T16:33:12Z","receivedAt":"2013-04-29T16:33:12Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ramkumar Ramachandra <artagnon@gmail.com> writes:\n\n> I agree that the \"confusion\" paragraph after [--] [<path>] can be\n> improved, but putting [--] in a paragraph of its own sounds like an\n> overkill.  Apart from other things, it means that every single git\n> command would need an identical [--] paragraph for consistency.\n\nThat is not a problem.  We need to say what command line argument X\n(e.g. <path>, but not limited to it) does in all pages for commands\nthat pay attention to X anyway.\n\nA more important reason to have them as separate entries is to avoid\ngiving a wrong impression that \"--\" is somehow related to <path>,\nwhich is where the mistake in the synopsis \"[[--] <path>...]\" that\nstarted this thread comes from.\n"},{"id":"215876","messageId":"CALkWK0=ZzE4gK4RZ8m9oAJgP76mWsYA2Z+Wasws8hnVgOQZR7Q@mail.gmail.com","threadId":"33565","inReplyTo":"7va9ohl2k7.fsf@alter.siamese.dyndns.org","subject":"Re: Re* [PATCH 5/7] git-log.txt: rewrite note on why \"--\" may be required","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-29T17:38:56Z","receivedAt":"2013-04-29T17:38:56Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Junio C Hamano wrote:\n> That is not a problem.\n> [...]\n> A more important reason to have them as separate entries is to avoid\n> giving a wrong impression that \"--\" is somehow related to <path>,\n\nOkay, makes sense then.  Queue it for this and shortlog; we can write\nit for the other manpages gradually.\n"}]}