{"thread":{"id":"33553","subject":"[PATCH 0/5] Documentation/shortlog improvements","startedAt":"2013-04-20T11:45:08Z","lastAt":"2013-04-22T14:55:40Z","messageCount":35,"participants":["Ramkumar Ramachandra","Jonathan Nieder","Junio C Hamano","Thomas Rast"],"isPatch":true,"patchVersion":1,"patchTotal":5},"messages":[{"id":"214913","messageId":"1366458313-7186-1-git-send-email-artagnon@gmail.com","threadId":"33553","inReplyTo":null,"subject":"[PATCH 0/5] Documentation/shortlog improvements","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-20T11:45:08Z","receivedAt":"2013-04-20T11:45:08Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Hi,\n\nI was going through the shortlog documentation and was saddened to see\nthat it was inaccurate and inconsistent with the log documentation. I\nuse shortlog quite a lot, and like it very much. So, here's a small\nseries fixing some problems.\n\n[3/5] and [4/5] came out of my desire to copy out parts of git-log.txt\ninto git-shortlog.txt (I had to fix git-log.txt first).\n\nThanks.\n\nRamkumar Ramachandra (5):\n git-shortlog.txt: remove (-h|--help) from OPTIONS\n builtin/shortlog.c: make usage string consistent with log\n git-log.txt: fix description of ..\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 | 10 +++++-----\n Documentation/git-shortlog.txt | 23 ++++++++++++++++++-----\n builtin/shortlog.c | 4 +---\n 3 files changed, 24 insertions(+), 13 deletions(-)\n\n-- \n1.8.2.1.506.gbce9ff0\n"},{"id":"214916","messageId":"1366458313-7186-2-git-send-email-artagnon@gmail.com","threadId":"33553","inReplyTo":"1366458313-7186-1-git-send-email-artagnon@gmail.com","subject":"[PATCH 1/5] git-shortlog.txt: remove (-h|--help) from OPTIONS","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-20T11:45:09Z","receivedAt":"2013-04-20T11:45:09Z","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.506.gbce9ff0\n"},{"id":"214918","messageId":"1366458313-7186-3-git-send-email-artagnon@gmail.com","threadId":"33553","inReplyTo":"1366458313-7186-1-git-send-email-artagnon@gmail.com","subject":"[PATCH 2/5] builtin/shortlog.c: make usage string consistent with log","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-20T11:45:10Z","receivedAt":"2013-04-20T11:45:10Z","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.506.gbce9ff0\n"},{"id":"214915","messageId":"1366458313-7186-4-git-send-email-artagnon@gmail.com","threadId":"33553","inReplyTo":"1366458313-7186-1-git-send-email-artagnon@gmail.com","subject":"[PATCH 3/5] git-log.txt: fix description of ..","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-20T11:45:11Z","receivedAt":"2013-04-20T11:45:11Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"First, and are ways to specify \"revisions\", not\n\"commits\", as gitrevisions.txt would indicate. Second,\n'..' is simply indicative of how users would normally\nwant to specify the rev spec: it need not conform to this form, and\ncan take any form that gitrevisions.txt lists. A 'git log :/quuxery'\nis perfectly valid, for instance. Make these two corrections to the\ndescription of '..' under OPTIONS.\n\nSigned-off-by: Ramkumar Ramachandra \n---\n Documentation/git-log.txt | 6 +++---\n 1 file changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 69db578..f03ae74 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -25,11 +25,11 @@ OPTIONS\n -------\n \n ..::\n-\tShow only commits between the named two commits. When\n+\tShow only commits between the named two revisions. 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+\tFor a more complete list of ways to spell ..,\n+\tsee linkgit:gitrevisions[7].\n \n --follow::\n \tContinue listing the history of a file beyond renames\n-- \n1.8.2.1.506.gbce9ff0\n"},{"id":"214917","messageId":"1366458313-7186-5-git-send-email-artagnon@gmail.com","threadId":"33553","inReplyTo":"1366458313-7186-1-git-send-email-artagnon@gmail.com","subject":"[PATCH 4/5] git-log.txt: rewrite note on why \"--\" may be required","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-20T11:45:12Z","receivedAt":"2013-04-20T11:45:12Z","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 the rev spec need not be a set of branch names or ref\nnames. Rewrite it to use the word \"revisions\".\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 f03ae74..1a9c3ca 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -75,8 +75,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 revisions, when confusion arises.\n \n include::rev-list-options.txt[]\n \n-- \n1.8.2.1.506.gbce9ff0\n"},{"id":"214914","messageId":"1366458313-7186-6-git-send-email-artagnon@gmail.com","threadId":"33553","inReplyTo":"1366458313-7186-1-git-send-email-artagnon@gmail.com","subject":"[PATCH 5/5] git-shortlog.txt: make SYNOPSIS match log, update OPTIONS","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-20T11:45:13Z","receivedAt":"2013-04-20T11:45:13Z","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.\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..d02ac03 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@@ -26,6 +26,13 @@ reference to the current repository.\n OPTIONS\n -------\n \n+..::\n+\tConsider only commits between the named two revisions. When\n+\teither or is omitted, it defaults to `HEAD`,\n+\ti.e. the tip of the current branch. For a more complete list\n+\tof ways to spell .., see\n+\tlinkgit:gitrevisions[7].\n+\n -n::\n --numbered::\n \tSort output according to the number of commits per author instead\n@@ -56,6 +63,16 @@ OPTIONS\n If width is `0` (zero) then indent the lines of the output without wrapping\n them.\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 revisions, when confusion arises.\n+\n+include::rev-list-options.txt[]\n \n MAPPING AUTHORS\n ---------------\n-- \n1.8.2.1.506.gbce9ff0\n"},{"id":"214945","messageId":"20130420222528.GA10043@elie.Belkin","threadId":"33553","inReplyTo":"1366458313-7186-4-git-send-email-artagnon@gmail.com","subject":"Re: [PATCH 3/5] git-log.txt: fix description of ..","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2013-04-20T22:25:28Z","receivedAt":"2013-04-20T22:25:28Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Ramkumar Ramachandra wrote:\n\n> First, and are ways to specify \"revisions\", not\n> \"commits\", as gitrevisions.txt would indicate.\n\nWhat's the difference between a revision and a commit? The definition\nin gitglossary(7) only confuses me.\n"},{"id":"214963","messageId":"7vy5ccwflw.fsf@alter.siamese.dyndns.org","threadId":"33553","inReplyTo":"1366458313-7186-4-git-send-email-artagnon@gmail.com","subject":"Re: [PATCH 3/5] git-log.txt: fix description of ..","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-04-21T06:40:59Z","receivedAt":"2013-04-21T06:40:59Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ramkumar Ramachandra writes:\n\n> First, and are ways to specify \"revisions\", not\n> \"commits\", as gitrevisions.txt would indicate. Second,\n> '..' is simply indicative of how users would normally\n> want to specify the rev spec: it need not conform to this form, and\n> can take any form that gitrevisions.txt lists. A 'git log :/quuxery'\n> is perfectly valid, for instance. Make these two corrections to the\n> description of '..' under OPTIONS.\n>\n> Signed-off-by: Ramkumar Ramachandra \n> ---\n> Documentation/git-log.txt | 6 +++---\n> 1 file changed, 3 insertions(+), 3 deletions(-)\n>\n> diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\n> index 69db578..f03ae74 100644\n> --- a/Documentation/git-log.txt\n> +++ b/Documentation/git-log.txt\n> @@ -25,11 +25,11 @@ OPTIONS\n> -------\n> \n> ..::\n> -\tShow only commits between the named two commits. When\n> +\tShow only commits between the named two revisions. 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> +\tFor a more complete list of ways to spell ..,\n> +\tsee linkgit:gitrevisions[7].\n\nA bigger issue is if it is a good idea to single out A..B like this\nin the enumeration of options and parameters. We are listing this\namong the optoins and pathspec, so this is where we _ought_ to be\nsaying that you can specify a revision range on the command line.\nWe use A..B only because it is the most commonly used form, asking\ne.g. \"show me the commit since v1.7.12 up to v1.8.0\", but this\nexisting headline makes it as if it is the _only_ form, which is\nsomewhat misleading.\n\nIt might be better _not_ to say .. here and on the\nsynopsis part, replace it with , and update the text\nto mention .. as a more concrete \"v1.0..v2.0\" example.\nPerhaps like\n\n ::\n\n\tShow only commits in the specified revision range. When no\n\t is specified, defaults to \"HEAD\" (i.e. the\n\twhole history leading to the current commit). v1.0..v2.0\n\tasks for commits since the commit tagged as version 1.0 up\n\tto the commit tagged as version 2.0. For a more complete\n\tlist of ways to spell this parameter, see \"Specifying\n\tRanges\" section of linkgit:gitrevisions[7].\n\nor something.\n\nDocumentation/gitrevisions.txt lists .., but does not\nmention that missing (or ) defaults to HEAD, which is\nworth adding there with or without the above suggested update.\n"},{"id":"214964","messageId":"7vtxn0wf4j.fsf@alter.siamese.dyndns.org","threadId":"33553","inReplyTo":"1366458313-7186-5-git-send-email-artagnon@gmail.com","subject":"Re: [PATCH 4/5] git-log.txt: rewrite note on why \"--\" may be required","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-04-21T06:51:24Z","receivedAt":"2013-04-21T06:51:24Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ramkumar Ramachandra 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 the rev spec need not be a set of branch names or ref\n> names. Rewrite it to use the word \"revisions\".\n>\n> Signed-off-by: Ramkumar Ramachandra \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 f03ae74..1a9c3ca 100644\n> --- a/Documentation/git-log.txt\n> +++ b/Documentation/git-log.txt\n> @@ -75,8 +75,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 revisions, when confusion arises.\n\nI think \"branch names\" was an attempt to make it more newbie\nfriendly by sacrificing technical accuracy. With the suggested\nupdate (see the review for the previous one), it would be easier to\nread if this part said \"options or the revision range\".\n\nTwo other things I noticed with the current text are:\n\n * As the synopsis section shows, on the command line, --options\n come first, then revision range and then pathspec. The order of\n the description should follow that as well. The current text\n shows .. at the very beginning, which is wrong.\n\n * The part with the new \"-L\" option seems to be throwing the\n overall formatting off. Its second paragraph \" and \n can take...\" is not indented to the same level as its first\n paragraph \"Trace the evolution of...\", and the following items,\n like \"--full-line-diff\" and \"[--] ...\" are indented one\n level too deeply.\n"},{"id":"214966","messageId":"7vppxowej9.fsf@alter.siamese.dyndns.org","threadId":"33553","inReplyTo":"1366458313-7186-6-git-send-email-artagnon@gmail.com","subject":"Re: [PATCH 5/5] git-shortlog.txt: make SYNOPSIS match log, update OPTIONS","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-04-21T07:04:10Z","receivedAt":"2013-04-21T07:04:10Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ramkumar Ramachandra writes:\n\n> +..::\n> +\tConsider only commits between the named two revisions. When\n> +\teither or is omitted, it defaults to `HEAD`,\n> +\ti.e. the tip of the current branch. For a more complete list\n> +\tof ways to spell .., see\n> +\tlinkgit:gitrevisions[7].\n> +\n\nThe same \"revision range\" comment, and also that this should be\nafter all options and before \"-- \", apply to this.\n\n> @@ -56,6 +63,16 @@ OPTIONS\n> If width is `0` (zero) then indent the lines of the output without wrapping\n> them.\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 revisions, when confusion arises.\n> +\n> +include::rev-list-options.txt[]\n\nWhile it is true that this page is missing many options, including\nrev-list-options.txt as-is is more harmful than helpful and the\npatch needs more work (hint: with \"ifdef::git-shortlog[]\" sprinkled\nin rev-list-options.txt).\n\nSome of the earlier one in rev-list-options are fine, but some\nothers are inappropriate in the context of shortlog. For example,\n--grep=, while it would internally work as it is told to\ndo, is unlikely to be clear how well/correctly worked when viewing\nthe end result. So are many others, such as --all-match,\n--walk-reflogs, --sparse, etc. Some e.g. --topo-order, do not make\nsense at all.\n\nI am not sure what the command would do if you give --stdin; the\ncommand wants to read from the standard input to operate as a filter\nfor \"git log\" output, but the \"--stdin\" from rev-list family wants\nto read revision range specifiers from the standard input. I do not\nthink it is something any sane user would want to do.\n"},{"id":"214968","messageId":"CALkWK0n7e-GQ8eBjgd4pnB5AzLGN0bik-n8_McbK68CvJh6P=A@mail.gmail.com","threadId":"33553","inReplyTo":"20130420222528.GA10043@elie.Belkin","subject":"Re: [PATCH 3/5] git-log.txt: fix description of ..","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-21T07:18:25Z","receivedAt":"2013-04-21T07:18:25Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Jonathan Nieder wrote:\n> What's the difference between a revision and a commit? The definition\n> in gitglossary(7) only confuses me.\n\nWhat's so confusing about it?\n\ncommit:: As a noun: A single point in the Git history; the entire\nhistory of a project is represented as a set of interrelated commits.\nThe word \"commit\" is often used by Git in the same places other\nrevision control systems use the words \"revision\" or \"version\". Also\nused as a short hand for commit object.\n\nrevision:: A particular state of files and directories which was\nstored in the object database. It is referenced by a commit object.\n\n-- 8< --\n\nThere a reference to \"revision\" in the \"commit\" description which\nmight be misleading.\n\nOtherwise, these are quite accurate. master~3:README is a valid revision,\nbut not a commit, for instance. Another problem with the word commit\nis that it doesn't encapsulate ranges like 'master~3..HEAD'. It would\nprobably help to add the terms \"commitish\" and \"treeish\" to the\nglossary to refer to \"rev specs\" (those in revisions.txt) that resolve\nto commits or trees. I'll give you two simple examples:\n\n1. In 'git show master:README', master is a treeish and master:README\nis a blob. If we were to say 'git blame master: -- README', it would\nerror out because master: is not a commitish, but a treeish.\n\n2. In 'git log master~3.. -- README', master~3.. is a commitish. In\ngeneral, log can take only rev specs that resolve to a commits.\nAlthough 'git log master:' doesn't error out, it doesn't make any\nsense either. Perhaps we should tighten it?\n"},{"id":"214969","messageId":"7vhaj0wdua.fsf@alter.siamese.dyndns.org","threadId":"33553","inReplyTo":"20130420222528.GA10043@elie.Belkin","subject":"Re: [PATCH 3/5] git-log.txt: fix description of ..","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-04-21T07:19:09Z","receivedAt":"2013-04-21T07:19:09Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder writes:\n\n> Ramkumar Ramachandra wrote:\n>\n>> First, and are ways to specify \"revisions\", not\n>> \"commits\", as gitrevisions.txt would indicate.\n>\n> What's the difference between a revision and a commit? The definition\n> in gitglossary(7) only confuses me.\n\nThey are the same, but I think it is irrelevant. We do not want\nrevision or commit there, anyway. We want a revision range there.\nThis is \"git log\" not \"git show\".\n"},{"id":"214971","messageId":"CALkWK0nFAzPPb0_jTRev6nuicCV81sRQAbe=277nhyyY8TnQ7A@mail.gmail.com","threadId":"33553","inReplyTo":"7vtxn0wf4j.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 4/5] git-log.txt: rewrite note on why \"--\" may be required","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-21T07:26:13Z","receivedAt":"2013-04-21T07:26:13Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Junio C Hamano wrote:\n> I think \"branch names\" was an attempt to make it more newbie\n> friendly by sacrificing technical accuracy. With the suggested\n> update (see the review for the previous one), it would be easier to\n> read if this part said \"options or the revision range\".\n\nWhy does it have to be a range? It might well be a list of revisions,\nso I'm tempted to stick with the word \"revisions\". As I wrote in the\nprevious email, I think \"revision\" can be referenced by any one of the\nsyntaxes specified in revisions.txt (this includes a \"committish\nrange\").\n"},{"id":"214972","messageId":"7v8v4cwd6g.fsf@alter.siamese.dyndns.org","threadId":"33553","inReplyTo":"CALkWK0nFAzPPb0_jTRev6nuicCV81sRQAbe=277nhyyY8TnQ7A@mail.gmail.com","subject":"Re: [PATCH 4/5] git-log.txt: rewrite note on why \"--\" may be required","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-04-21T07:33:27Z","receivedAt":"2013-04-21T07:33:27Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ramkumar Ramachandra writes:\n\n> Junio C Hamano wrote:\n>> I think \"branch names\" was an attempt to make it more newbie\n>> friendly by sacrificing technical accuracy. With the suggested\n>> update (see the review for the previous one), it would be easier to\n>> read if this part said \"options or the revision range\".\n>\n> Why does it have to be a range? It might well be a list of revisions,\n\nStudy \"Specifying Ranges\" section of gitrevisions and come back,\nperhaps?\n\nA list of revisions is merely a way to specify \"revision range\" that\nare reachable from any of these revisions listed. \"log A B\" won't\nstop by just showing A and B (that would be \"show A B\"), but will\nlist those that are reachable from A B, so in the context of\ndiscussing the arguments given to \"git log\" command, \"A B\" is still\n\"revision range\".\n"},{"id":"214973","messageId":"CALkWK0kiT7vggXgqGs2iiMooiw7TyJEgr2=Yy06S7H1NKiWJ3g@mail.gmail.com","threadId":"33553","inReplyTo":"7v8v4cwd6g.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 4/5] git-log.txt: rewrite note on why \"--\" may be required","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-21T07:38:00Z","receivedAt":"2013-04-21T07:38:00Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Junio C Hamano wrote:\n> A list of revisions is merely a way to specify \"revision range\" that\n> are reachable from any of these revisions listed. \"log A B\" won't\n> stop by just showing A and B (that would be \"show A B\"), but will\n> list those that are reachable from A B, so in the context of\n> discussing the arguments given to \"git log\" command, \"A B\" is still\n> \"revision range\".\n\n... and what about 'git log HEAD^!'? Is that a range? What about\n'git log HEAD:README' (hint: it doesn't error out)? I would argue that\n\"A B\" is not inherently a revision range, but rather two revisions.\nIt's upto different commands to interpret it differently.\n\nThen again, in the context of log, we just want ranges (also\nconsidering we had .. for this long, and I didn't even\nobject to it). So I'll go with your \"revision range\", but I won't\nclaim that it's technically accurate.\n"},{"id":"214975","messageId":"7v4nf0wcw3.fsf@alter.siamese.dyndns.org","threadId":"33553","inReplyTo":"7v8v4cwd6g.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 4/5] git-log.txt: rewrite note on why \"--\" may be required","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-04-21T07:39:40Z","receivedAt":"2013-04-21T07:39:40Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Ramkumar Ramachandra writes:\n>\n>> Junio C Hamano wrote:\n>>> I think \"branch names\" was an attempt to make it more newbie\n>>> friendly by sacrificing technical accuracy. With the suggested\n>>> update (see the review for the previous one), it would be easier to\n>>> read if this part said \"options or the revision range\".\n>>\n>> Why does it have to be a range? It might well be a list of revisions,\n>\n> Study \"Specifying Ranges\" section of gitrevisions and come back,\n> perhaps?\n\nA bit more specifically, there is a reason why we list \"Specifying\nRevisions\" and \"Specifying Ranges\" separately in that manual page.\n\nI think you are trying explain \"git log --short A B ^C\" as if it\ntakes \"--short\" (which is an option), \"A\", \"B\", and \"^C\" (all of\nwhich are revisions). And I am saying that is wrong.\n\nIt is \"--short\" (which is an option) and \"A B ^C\" (which is a\nrevision range).\n\n\"git log --short A\" is taking \"--short\" (an option) and \"A\". This\n\"A\" is still a revision range and not a single revision. It is a\nsingle commit that is used to name a revision range which is the\nentire history behind the commit \"A\".\n"},{"id":"214976","messageId":"20130421074118.GE10429@elie.Belkin","threadId":"33553","inReplyTo":"CALkWK0n7e-GQ8eBjgd4pnB5AzLGN0bik-n8_McbK68CvJh6P=A@mail.gmail.com","subject":"Re: [PATCH 3/5] git-log.txt: fix description of ..","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2013-04-21T07:41:18Z","receivedAt":"2013-04-21T07:41:18Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Ramkumar Ramachandra wrote:\n\n> What's so confusing about it?\n[...]\n> revision:: A particular state of files and directories which was\n> stored in the object database. It is referenced by a commit object.\n\nSo a revision is a tree? (\"one of the things pointed to by a commit\nobject, representing a particular state of files and directories\")\n"},{"id":"214977","messageId":"7vzjwsuxzp.fsf@alter.siamese.dyndns.org","threadId":"33553","inReplyTo":"CALkWK0kiT7vggXgqGs2iiMooiw7TyJEgr2=Yy06S7H1NKiWJ3g@mail.gmail.com","subject":"Re: [PATCH 4/5] git-log.txt: rewrite note on why \"--\" may be required","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-04-21T07:46:50Z","receivedAt":"2013-04-21T07:46:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ramkumar Ramachandra writes:\n\n> ... and what about 'git log HEAD^!'? Is that a range? \n\nOf course it _is_ a range; didn't you read it in the \"specifying\nranges\" section? It is a short-hand for \"include HEAD, exclude its\nparents\", and you can further combine it with other starting points.\n\n> What about 'git log HEAD:README' (hint: it doesn't error out)?\n\nSounds like a bug, if it doesn't.\n\nPatches welcome---I suspect that it can be solved the same way as\nthe recent cherry-pick patch by Miklos.\n\n> I would argue that \"A B\" is not inherently a revision range, but\n> rather two revisions. It's upto different commands to interpret\n> it differently.\n\nThat is why I said this is \"git log\", not \"git show\".\n"},{"id":"214978","messageId":"CALkWK0nwrwPSqOCabBsnGsrAfxphYiUXhfpT7DnSvo6RKftqjA@mail.gmail.com","threadId":"33553","inReplyTo":"7v4nf0wcw3.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 4/5] git-log.txt: rewrite note on why \"--\" may be required","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-21T07:57:20Z","receivedAt":"2013-04-21T07:57:20Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Junio C Hamano wrote:\n> I think you are trying explain \"git log --short A B ^C\" as if it\n> takes \"--short\" (which is an option), \"A\", \"B\", and \"^C\" (all of\n> which are revisions). And I am saying that is wrong.\n>\n> It is \"--short\" (which is an option) and \"A B ^C\" (which is a\n> revision range).\n\nGot it. Your explanation makes more sense.\n"},{"id":"214979","messageId":"CALkWK0kEngwYQieR=Xmvzu+XqBe+ZFxiWj0C8M-euFavDDaD2Q@mail.gmail.com","threadId":"33553","inReplyTo":"7vzjwsuxzp.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 4/5] git-log.txt: rewrite note on why \"--\" may be required","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-21T08:00:06Z","receivedAt":"2013-04-21T08:00:06Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Junio C Hamano wrote:\n> Sounds like a bug, if it doesn't.\n>\n> Patches welcome---I suspect that it can be solved the same way as\n> the recent cherry-pick patch by Miklos.\n\nIt's not as pressing as the glaring Documentation inaccuracies, so\nI'll queue the task.\n\nTo exclude this case, I would say the most technically accurate\ndescription of what 'git log' takes is a \"committish range\" (basically\na \"revision range\" that resolves to commits).\n"},{"id":"214980","messageId":"20130421080907.GF10429@elie.Belkin","threadId":"33553","inReplyTo":"CALkWK0kEngwYQieR=Xmvzu+XqBe+ZFxiWj0C8M-euFavDDaD2Q@mail.gmail.com","subject":"Re: [PATCH 4/5] git-log.txt: rewrite note on why \"--\" may be required","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2013-04-21T08:09:07Z","receivedAt":"2013-04-21T08:09:07Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Ramkumar Ramachandra wrote:\n\n> I would say the most technically accurate\n> description of what 'git log' takes is a \"committish range\" (basically\n> a \"revision range\" that resolves to commits).\n\nWhat is a revision range that doesn't resolve to commits? Am I wrong\nin thinking revision is nothing more than a synonym for commit?\n\nWhen gitrevisions(7) says \"A revision parameter typically, but\nnot necessarily, names a commit object\", I suspect it is residue from\n3a45f625 trying to apologize for the extended SHA1 syntax parser being\ncalled \"git rev-parse\" instead of \"git object-name-parse\".\n"},{"id":"214982","messageId":"CALkWK0mmvwnRzq5eYTzvZRmEwn7nyDLe5cJsV1iQvNnh1Y7xEw@mail.gmail.com","threadId":"33553","inReplyTo":"CAPc5daV39HsoRR2pj34Tz1kQKFVRrp+NZpMM2BremocqvToA+A@mail.gmail.com","subject":"Re: [PATCH 4/5] git-log.txt: rewrite note on why \"--\" may be required","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-21T08:13:24Z","receivedAt":"2013-04-21T08:13:24Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Junio C Hamano wrote:\n> A revision range is a slice of history, so you don't need any further\n> adjective.\n>\n> Please don't introduce new words that do not add any accuracies nor value.\n\nI was just saying: I don't want to introduce new terms either. I\nthink revisions.txt needs to be fixed. Under the Specifying Ranges\nsection:\n\n''::\n\tInclude commits that are reachable from (i.e. ancestors of)\n\t.\n\nThis doesn't make sense because might as well refer to a blob*.\nSo this should say s// that names a commit object/.\n\n* The first line in the Specifying Revisions section: A revision\nparameter '' typically, but not necessarily, names a commit\nobject.\n"},{"id":"214983","messageId":"CALkWK0=BkCxhGvjWwTHe83LHQ7R2t-EAMr6H9VQ1AvBjgYerBA@mail.gmail.com","threadId":"33553","inReplyTo":"20130421080907.GF10429@elie.Belkin","subject":"Re: [PATCH 4/5] git-log.txt: rewrite note on why \"--\" may be required","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-21T08:15:52Z","receivedAt":"2013-04-21T08:15:52Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Jonathan Nieder wrote:\n> Am I wrong\n> in thinking revision is nothing more than a synonym for commit?\n\nYes. If master@{3}~2:README isn't a revision, what is it? And it\nfits into the Specifying Revisions section quite snugly: I see no\nreason to mangle the meaning of \"revision\".\n"},{"id":"214984","messageId":"20130421081705.GG10429@elie.Belkin","threadId":"33553","inReplyTo":"CAPc5daVcovqrHP-YWnkcQWwev5TW5S8ioX-bWyAnNG2PTg_XMw@mail.gmail.com","subject":"[PATCH/RFC] glossary: a revision is just a commit","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2013-04-21T08:17:05Z","receivedAt":"2013-04-21T08:17:05Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"The current definition of 'revision' sounds like it is saying that a\nrevision is a tree object. In reality it is just a commit.\n\nThis should be especially useful for people used to other revision\ncontrol systems trying to see how familiar concepts translate into git\nterms.\n\nReported-by: Ramkumar Ramachandra \nSigned-off-by: Jonathan Nieder \n---\nJunio C Hamano wrote:\n> On Apr 21, 2013 12:41 AM, \"Jonathan Nieder\" wrote:\n\n>>> revision:: A particular state of files and directories which was\n>>> stored in the object database. It is referenced by a commit object.\n>>\n>> So a revision is a tree?\n[...]\n> That's a historical misnomer. Some places in the documentation use revision\n> as if the word were interchangeable with object name, and HEAD:path listed\n> in specifying revision section is a prime example of it. What the section\n> lists is historically called extended SHA-1 expression, essentially what\n> get_sha1() can grok down to a single object name (as opposed to a slice of\n> history, which is a revision range).\n\nThanks.\n\n Documentation/glossary-content.txt | 4 +---\n 1 file changed, 1 insertion(+), 3 deletions(-)\n\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex eb7ba84f..521fceeb 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -430,9 +430,7 @@ should not be combined with other pathspec.\n \t<> left behind.\n \n [[def_revision]]revision::\n-\tA particular state of files and directories which was stored in the\n-\t<>. It is referenced by a\n-\t<>.\n+\tSynonym for <> (the noun).\n \n [[def_rewind]]rewind::\n \tTo throw away part of the development, i.e. to assign the\n-- \n1.8.2.1\n"},{"id":"214985","messageId":"20130421081755.GH10429@elie.Belkin","threadId":"33553","inReplyTo":"CALkWK0=BkCxhGvjWwTHe83LHQ7R2t-EAMr6H9VQ1AvBjgYerBA@mail.gmail.com","subject":"Re: [PATCH 4/5] git-log.txt: rewrite note on why \"--\" may be required","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2013-04-21T08:17:56Z","receivedAt":"2013-04-21T08:17:56Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Ramkumar Ramachandra wrote:\n\n> Yes. If master@{3}~2:README isn't a revision, what is it?\n\nAn extended SHA1 expression referring to a blob.\n"},{"id":"214987","messageId":"CALkWK0n+Q6EWy6StGvgwvLf5mZqZfhaCvG70zD=2a0rK3qRLCQ@mail.gmail.com","threadId":"33553","inReplyTo":"CALkWK0mmvwnRzq5eYTzvZRmEwn7nyDLe5cJsV1iQvNnh1Y7xEw@mail.gmail.com","subject":"Re: [PATCH 4/5] git-log.txt: rewrite note on why \"--\" may be required","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-21T08:23:28Z","receivedAt":"2013-04-21T08:23:28Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Ramkumar Ramachandra wrote:\n> ''::\n> Include commits that are reachable from (i.e. ancestors of)\n> .\n>\n> This doesn't make sense because might as well refer to a blob*.\n> So this should say s// that names a commit object/.\n\nIn other words, my fix is to change the meaning of \"revision range\" to\nnot literally mean \"range of revisions\", but rather \"range of\n(revisions that are commits)\". I think it is more sensible than\nJonathan's fix which breaks too many existing things; most\nsignificantly, the names rev-parse/rev-list.\n"},{"id":"214988","messageId":"7vvc7guvu4.fsf@alter.siamese.dyndns.org","threadId":"33553","inReplyTo":"20130421080907.GF10429@elie.Belkin","subject":"Re: [PATCH 4/5] git-log.txt: rewrite note on why \"--\" may be required","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-04-21T08:33:23Z","receivedAt":"2013-04-21T08:33:23Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder writes:\n\n> Ramkumar Ramachandra wrote:\n>\n>> I would say the most technically accurate\n>> description of what 'git log' takes is a \"committish range\" (basically\n>> a \"revision range\" that resolves to commits).\n>\n> What is a revision range that doesn't resolve to commits? Am I wrong\n> in thinking revision is nothing more than a synonym for commit?\n>\n> When gitrevisions(7) says \"A revision parameter typically, but\n> not necessarily, names a commit object\", I suspect it is residue from\n> 3a45f625 trying to apologize for the extended SHA1 syntax parser being\n> called \"git rev-parse\" instead of \"git object-name-parse\".\n\n - A revision range is a slice of history. There is no need for\n \"committish revision range\" as there is no other kinds of ranges.\n\n - A revision should be a synonym to a committish, as glossary\n defines. We historically used \"revision\" more or less\n interchangeably with \"object name\", especially \"an extended SHA-1\n expression that is used as an object name\", to mean whatever\n get_sha1() can grok down to a single object name. This must be\n rectified to avoid causing confusion to new readers of our\n documentation.\n\n - Documentation/revisions.txt needs to be cleaned up. It lists\n \"specifying revisions\" and \"specifying ranges\", which is a good\n start primarily because some notations used in ranges are not\n revisions (e.g. \"^C\"), but it should have three (not two) sections.\n\n They are: \"specifying revisions\", \"specifying object names\", and\n \"specifying ranges\". Move non committish specification such as\n : from the current \"specifying revisions\" section\n and make the new \"object names\" section. The \"ranges\" section is\n already written in terms of revisions, and does not need any\n update, once we clarify the definition of a \"revision\" as\n \"committish\".\n"},{"id":"215002","messageId":"CALkWK0nHbm4La4kJ6cNzEnMas5B7Q2M=z_9d+O6iNX2r2bi98A@mail.gmail.com","threadId":"33553","inReplyTo":"7vvc7guvu4.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 4/5] git-log.txt: rewrite note on why \"--\" may be required","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-21T09:05:46Z","receivedAt":"2013-04-21T09:05:46Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Junio C Hamano wrote:\n> - A revision range is a slice of history. There is no need for\n> \"committish revision range\" as there is no other kinds of ranges.\n\nFor the record, 'git rev-parse master:README..HEAD@{3}~2' works just\nfine. I don't know whether you want to consider it \"sensible\" or not,\nbut the current revisions.txt is consistent with this.\n\n> - A revision should be a synonym to a committish, as glossary\n> defines. We historically used \"revision\" more or less\n> interchangeably with \"object name\", especially \"an extended SHA-1\n> expression that is used as an object name\", to mean whatever\n> get_sha1() can grok down to a single object name. This must be\n> rectified to avoid causing confusion to new readers of our\n> documentation.\n\nThe question is: who is the authority on this? The combination of\nrev-parse, rev-list, and revisions.txt, or gitglossary.txt.\n\n> They are: \"specifying revisions\", \"specifying object names\", and\n> \"specifying ranges\".\n\nPersonally, I don't like giving commit objects a special status, and\nlike things just the way they currently are. Why do you want to\nseparate \"revisions\" (which are really just \"extended SHA-1\nexpressions\" that incidentally resolve to commit objects) and\n\"extended SHA-1 expressions that resolve to objects other than\ncommits\"? Is the current hand-wavy unclear gitglossary.txt the only\nbasis for your argument?\n"},{"id":"215003","messageId":"CALkWK0=T-ere6PFZxVuymjHwRWS6==p_W2Qy+mtN7eXj6qNZ0g@mail.gmail.com","threadId":"33553","inReplyTo":"CALkWK0nHbm4La4kJ6cNzEnMas5B7Q2M=z_9d+O6iNX2r2bi98A@mail.gmail.com","subject":"Re: [PATCH 4/5] git-log.txt: rewrite note on why \"--\" may be required","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-04-21T09:46:04Z","receivedAt":"2013-04-21T09:46:04Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Ramkumar Ramachandra wrote:\n> For the record, 'git rev-parse master:README..HEAD@{3}~2' works just\n> fine. I don't know whether you want to consider it \"sensible\" or not,\n> but the current revisions.txt is consistent with this.\n\nrev-list errors out though:\n\n error: Object 15bfea is a blob, not a commit\n fatal: Invalid revision range master:README..HEAD@{3}~2\n\nHence my suggestion to change the meaning of what a valid \"revision\nrange\" is (using rev-list as the guideline) , and be done with it.\n"},{"id":"215004","messageId":"20130421100939.GI10429@elie.Belkin","threadId":"33553","inReplyTo":"CALkWK0nHbm4La4kJ6cNzEnMas5B7Q2M=z_9d+O6iNX2r2bi98A@mail.gmail.com","subject":"Re: [PATCH 4/5] git-log.txt: rewrite note on why \"--\" may be required","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2013-04-21T10:09:39Z","receivedAt":"2013-04-21T10:09:39Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Ramkumar Ramachandra wrote:\n\n> Why do you want to\n> separate \"revisions\" (which are really just \"extended SHA-1\n> expressions\" that incidentally resolve to commit objects) and\n> \"extended SHA-1 expressions that resolve to objects other than\n> commits\"?\n\nNo one I've met actually uses the word \"revisions\" to mean anything\nother than the English-language meaning of \"revisions\", which in a Git\ncontext is \"commits\". There's value in matching common usage.\n"},{"id":"215028","messageId":"7vy5cbso82.fsf@alter.siamese.dyndns.org","threadId":"33553","inReplyTo":"20130421081705.GG10429@elie.Belkin","subject":"Re: [PATCH/RFC] glossary: a revision is just a commit","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-04-21T19:00:45Z","receivedAt":"2013-04-21T19:00:45Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder writes:\n\n> The current definition of 'revision' sounds like it is saying that a\n> revision is a tree object. In reality it is just a commit.\n>\n> This should be especially useful for people used to other revision\n> control systems trying to see how familiar concepts translate into git\n> terms.\n>\n> Reported-by: Ramkumar Ramachandra \n> Signed-off-by: Jonathan Nieder \n> ---\n\nI think the existing glossary text is just confusing (it does wants\nto refer to a commit (noun) as a concept, as opposed to its concrete\nrealization, i.e. a commit object, and tries to do so but does a bad\njob).\n\nYour update is an improvement, but there may need a note that says\nthat various web pages and documents, especially historical ones\n[*1*], may loosely use this word to refer to any single object that\nis not necessarily a commit at times.\n\n> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\n> index eb7ba84f..521fceeb 100644\n> --- a/Documentation/glossary-content.txt\n> +++ b/Documentation/glossary-content.txt\n> @@ -430,9 +430,7 @@ should not be combined with other pathspec.\n> \t<> left behind.\n> \n> [[def_revision]]revision::\n> -\tA particular state of files and directories which was stored in the\n> -\t<>. It is referenced by a\n> -\t<>.\n> +\tSynonym for <> (the noun).\n> \n> [[def_rewind]]rewind::\n> \tTo throw away part of the development, i.e. to assign the\n\n\n[Footnote]\n\n*1* The \"rev-parse\" command started as a tool to parse \"revisions\" aka\n\"commit\", \"revision range\" e.g. \"A..B\" and non-revisions (pathspecs)\nand flags. It was primarily designed as a way to sift arguments\ngiven to \"git mylog -p A..B Makefile\", so that a scripted \"mylog\"\ncan turn it into a pipeline that feeds \"git rev-list A..B Makefile\"\noutput as the input to \"git diff-tree -p --stdin Makefile\".\n\nThis was back when we did not even have non-committish extended\nSHA-1 object name notation. From the very start, \"rev\" in the name\n\"rev-parse\" did not even mean that it is limited to \"revision\" aka\n\"commit\". Later we added tree:path form of extended SHA-1 notation\nand \"rev-parse --verify $it\" has become its primary usage, while its\nrole as argument sifter has diminished as we made \"log\" a built-in,\nnot a pipeline. Around that time, we loosely started calling\nanything that get_sha1() can turn into an object name a \"revision\".\n\nAlso 99.9% of the time people use it to parse committish in real\nlife.\n\nFor these reasons, I do not think it is wise to rename \"rev-parse\"\nto \"object-name-parse\". \"rev\" in \"rev-parse\" may be related to\n\"revisions\", and while it technically can operate on \"revisions\" (in\nthe colloquial \"object name\" sense), it is not limited to revisions.\nAnd when it is used for revisions it mostly is used for \"revisions\"\n(in the \"nothing but committish\" sense). The name that most\nfaithfully reflects the use of the command is \"git kitchen-sink\"\nthese days.\n\nThe user still needs to know that in some context, \"revision\" may\nloosely refer to \"object name\" when talking about a single object,\nif only to understand the name of that command, let alone various\ntutorials, screencasts and web resources people made over time.\n"},{"id":"215050","messageId":"7vmwsrqocu.fsf@alter.siamese.dyndns.org","threadId":"33553","inReplyTo":"7vtxn0wf4j.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 4/5] git-log.txt: rewrite note on why \"--\" may be required","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-04-22T02:40:49Z","receivedAt":"2013-04-22T02:40:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Two other things I noticed with the current text are:\n> ...\n> * The part with the new \"-L\" option seems to be throwing the\n> overall formatting off. Its second paragraph \" and \n> can take...\" is not indented to the same level as its first\n> paragraph \"Trace the evolution of...\", and the following items,\n> like \"--full-line-diff\" and \"[--] ...\" are indented one\n> level too deeply.\n\nThis is a minimalistic patch to fix the formatting. I removed the\nextra sentence after the enumeration and moved it to the end of the\nmain text, but somebody may have a better idea to persuade AsciiDoc\nto format it in a more reasonable way while keeping the sentence\nthere.\n\n-- >8 --\nSubject: line-log: fix documentation formatting\n\nThe second paragraph of the added description for the -L option\n\" and can take one of these forms:\", and the list of\nforms that follow the headline, were indented one level too short,\ndue to the missing \"+\" to signal that the next paragraph continues\nthe previous one.\n\nAlso \"You can specify this option more than once\" is about the -L\noption, not about its various forms of starting and ending points.\nMove it to the end of the main text.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/git-log.txt | 5 ++---\n 1 file changed, 2 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 4850226..0959f9d 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -76,12 +76,11 @@ produced by --stat etc.\n \tnot give any pathspec limiters. This is currently limited to\n \ta walk starting from a single revision, i.e., you may only\n \tgive zero or one positive revision arguments.\n-\n+\tYou can specify this option more than once.\n++\n and can take one of these forms:\n \n include::line-range-format.txt[]\n-You can specify this option more than once.\n-\n \n --full-line-diff::\n \tAlways print the interesting range even if the current commit\n"},{"id":"215066","messageId":"871ua2sy95.fsf@linux-k42r.v.cablecom.net","threadId":"33553","inReplyTo":"7vmwsrqocu.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 4/5] git-log.txt: rewrite note on why \"--\" may be required","fromName":"Thomas Rast","fromEmail":"trast@inf.ethz.ch","sentAt":"2013-04-22T09:36:22Z","receivedAt":"2013-04-22T09:36:22Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Junio C Hamano writes:\n\n> This is a minimalistic patch to fix the formatting. I removed the\n> extra sentence after the enumeration and moved it to the end of the\n> main text, but somebody may have a better idea to persuade AsciiDoc\n> to format it in a more reasonable way while keeping the sentence\n> there.\n>\n> -- >8 --\n> Subject: line-log: fix documentation formatting\n>\n> The second paragraph of the added description for the -L option\n> \" and can take one of these forms:\", and the list of\n> forms that follow the headline, were indented one level too short,\n> due to the missing \"+\" to signal that the next paragraph continues\n> the previous one.\n>\n> Also \"You can specify this option more than once\" is about the -L\n> option, not about its various forms of starting and ending points.\n> Move it to the end of the main text.\n>\n> Signed-off-by: Junio C Hamano \n> ---\n> Documentation/git-log.txt | 5 ++---\n> 1 file changed, 2 insertions(+), 3 deletions(-)\n>\n> diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\n> index 4850226..0959f9d 100644\n> --- a/Documentation/git-log.txt\n> +++ b/Documentation/git-log.txt\n> @@ -76,12 +76,11 @@ produced by --stat etc.\n> \tnot give any pathspec limiters. This is currently limited to\n> \ta walk starting from a single revision, i.e., you may only\n> \tgive zero or one positive revision arguments.\n> -\n> +\tYou can specify this option more than once.\n> ++\n> and can take one of these forms:\n> \n> include::line-range-format.txt[]\n> -You can specify this option more than once.\n> -\n> \n\nSorry for being a bit late to this. I think it's a good solution;\nputting \"You can specify this option more than once\" after all the other\ntext was probably worse because it gets lost down there.\n\nAs for\n\n> --full-line-diff::\n> \tAlways print the interesting range even if the current commit\n\nThat's just stale and not currently implemented. Sigh. We should\nremove it.\n\n-- >8 --\nSubject: [PATCH] git-log(1): remove --full-line-diff description\n\nThis option is a remnant of an earlier log -L version, and not\ncurrently implemented. Remove it until (if at all) it is implemented\nagain.\n\nSigned-off-by: Thomas Rast \n---\n Documentation/git-log.txt | 4 ----\n 1 file changed, 4 deletions(-)\n\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 0959f9d..65707ce 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -82,10 +82,6 @@ produced by --stat etc.\n \n include::line-range-format.txt[]\n \n---full-line-diff::\n-\tAlways print the interesting range even if the current commit\n-\tdoes not change any line of the range.\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.844.g59e84de.dirty\n"},{"id":"215067","messageId":"87vc7erjhc.fsf@linux-k42r.v.cablecom.net","threadId":"33553","inReplyTo":"871ua2sy95.fsf@linux-k42r.v.cablecom.net","subject":"Re: [PATCH 4/5] git-log.txt: rewrite note on why \"--\" may be required","fromName":"Thomas Rast","fromEmail":"trast@inf.ethz.ch","sentAt":"2013-04-22T09:40:47Z","receivedAt":"2013-04-22T09:40:47Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Thomas Rast writes:\n\n> -- >8 --\n> Subject: [PATCH] git-log(1): remove --full-line-diff description\n\nBTW, I generated this with your jc/format-patch, but it stopped working\nafter fc/send-email-annotate made it into next; I need this on top. Am\nI missing something?\n\n-- >8 --\nSubject: [PATCH] FIXUP jc/format-patch: adapt for fc/send-email-annotate\n\n2a4c260 (format-patch: add format.coverLetter configuration variable,\n2013-04-07) changed the coverletter variable to -1 by default, so the\ndie(\"... incompatible\") always triggers. Test if it is >0 instead.\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 4804229..c972e62 100644\n--- a/builtin/log.c\n+++ b/builtin/log.c\n@@ -1247,7 +1247,7 @@ int cmd_format_patch(int argc, const char **argv, const char *prefix)\n \t/* Set defaults and check incompatible options */\n \tif (rev.inline_single) {\n \t\tuse_stdout = 1;\n-\t\tif (cover_letter)\n+\t\tif (cover_letter > 0)\n \t\t\tdie(_(\"inline-single and cover-letter are incompatible.\"));\n \t\tif (thread)\n \t\t\tdie(_(\"inline-single and thread are incompatible.\"));\n-- \n1.8.2.1.844.g59e84de.dirty\n"},{"id":"215083","messageId":"7va9oqr4wj.fsf@alter.siamese.dyndns.org","threadId":"33553","inReplyTo":"87vc7erjhc.fsf@linux-k42r.v.cablecom.net","subject":"Re: [PATCH 4/5] git-log.txt: rewrite note on why \"--\" may be required","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-04-22T14:55:40Z","receivedAt":"2013-04-22T14:55:40Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Thomas Rast writes:\n\n> Thomas Rast writes:\n>\n>> -- >8 --\n>> Subject: [PATCH] git-log(1): remove --full-line-diff description\n>\n> BTW, I generated this with your jc/format-patch, but it stopped working\n> after fc/send-email-annotate made it into next; I need this on top. Am\n> I missing something?\n\nNo, the topic has been stalled and left behind and needs to be\nrebased on top of that other topic with your patch. Thanks.\n\nIt also needs a lot more work to de-mime its output to be eligible\nfor 'next', though.\n\n> -- >8 --\n> Subject: [PATCH] FIXUP jc/format-patch: adapt for fc/send-email-annotate\n>\n> 2a4c260 (format-patch: add format.coverLetter configuration variable,\n> 2013-04-07) changed the coverletter variable to -1 by default, so the\n> die(\"... incompatible\") always triggers. Test if it is >0 instead.\n> ---\n> builtin/log.c | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/builtin/log.c b/builtin/log.c\n> index 4804229..c972e62 100644\n> --- a/builtin/log.c\n> +++ b/builtin/log.c\n> @@ -1247,7 +1247,7 @@ int cmd_format_patch(int argc, const char **argv, const char *prefix)\n> \t/* Set defaults and check incompatible options */\n> \tif (rev.inline_single) {\n> \t\tuse_stdout = 1;\n> -\t\tif (cover_letter)\n> +\t\tif (cover_letter > 0)\n> \t\t\tdie(_(\"inline-single and cover-letter are incompatible.\"));\n> \t\tif (thread)\n> \t\t\tdie(_(\"inline-single and thread are incompatible.\"));\n"}]}