{"thread":{"id":"42687","subject":"name for A..B ranges?","startedAt":"2016-06-22T07:26:05Z","lastAt":"2016-08-31T16:26:32Z","messageCount":107,"participants":["Philip Oakley","Jeff King","Junio C Hamano","Marc Branchaud","Jakub Narębski"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"289832","messageId":"0648000B273C412AB7140AE959EBC99A@PhilipOakley","threadId":"42687","inReplyTo":null,"subject":"name for A..B ranges?","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-06-22T07:25:59Z","receivedAt":"2016-06-22T07:26:05Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Hi,\n\nIs there a common name for the A..B range format (two dots) that would \ncomplement the A...B (three dots) symmetric range format's name?\n\nI was looking at the --left-right distinctions and noticed that the trail \nback to the symmetric range description was rather thin (it's buried within \ngitrevisions:Specifying Ranges, and even then its called a symmetric \ndifference.\n\nPhilip \n\n"},{"id":"290026","messageId":"20160624160943.GA3170@sigill.intra.peff.net","threadId":"42687","inReplyTo":"0648000B273C412AB7140AE959EBC99A@PhilipOakley","subject":"Re: name for A..B ranges?","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2016-06-24T16:09:43Z","receivedAt":"2016-06-24T16:09:49Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Jun 22, 2016 at 08:25:59AM +0100, Philip Oakley wrote:\n\n> Is there a common name for the A..B range format (two dots) that would\n> complement the A...B (three dots) symmetric range format's name?\n> \n> I was looking at the --left-right distinctions and noticed that the trail\n> back to the symmetric range description was rather thin (it's buried within\n> gitrevisions:Specifying Ranges, and even then its called a symmetric\n> difference.\n\nI would just call it a range, or possibly a set difference. But I don't\nthink we have any established naming beyond that.\n\n-Peff\n"},{"id":"290028","messageId":"xmqqh9cih6ym.fsf@gitster.mtv.corp.google.com","threadId":"42687","inReplyTo":"20160624160943.GA3170@sigill.intra.peff.net","subject":"Re: name for A..B ranges?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-06-24T16:44:49Z","receivedAt":"2016-06-24T16:44:56Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> On Wed, Jun 22, 2016 at 08:25:59AM +0100, Philip Oakley wrote:\n>\n>> Is there a common name for the A..B range format (two dots) that would\n>> complement the A...B (three dots) symmetric range format's name?\n>> \n>> I was looking at the --left-right distinctions and noticed that the trail\n>> back to the symmetric range description was rather thin (it's buried within\n>> gitrevisions:Specifying Ranges, and even then its called a symmetric\n>> difference.\n>\n> I would just call it a range, or possibly a set difference. But I don't\n> think we have any established naming beyond that.\n\nYup, I think \"range\" is the commonly used word in discussions here.\nWhen inventing A...B as a new thing in addition to A..B, we called\nthe former \"symmetric difference\", and what is implied by that is\nthe latter is \"asymmetric difference\"; we do not say that unless we\nare contrasting between the two, though.\n"},{"id":"290131","messageId":"E61B46FFA8874DD3973AA96BE5B36790@PhilipOakley","threadId":"42687","inReplyTo":"xmqqh9cih6ym.fsf@gitster.mtv.corp.google.com","subject":"Re: name for A..B ranges?","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-06-25T13:50:16Z","receivedAt":"2016-06-25T13:50:25Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \n> Jeff King writes:\n>\n>> On Wed, Jun 22, 2016 at 08:25:59AM +0100, Philip Oakley wrote:\n>>\n>>> Is there a common name for the A..B range format (two dots) that would\n>>> complement the A...B (three dots) symmetric range format's name?\n>>>\n>>> I was looking at the --left-right distinctions and noticed that the \n>>> trail\n>>> back to the symmetric range description was rather thin (it's buried \n>>> within\n>>> gitrevisions:Specifying Ranges, and even then its called a symmetric\n>>> difference.\n>>\n>> I would just call it a range, or possibly a set difference. But I don't\n>> think we have any established naming beyond that.\n>\n> Yup, I think \"range\" is the commonly used word in discussions here.\n> When inventing A...B as a new thing in addition to A..B, we called\n> the former \"symmetric difference\", and what is implied by that is\n> the latter is \"asymmetric difference\"; we do not say that unless we\n> are contrasting between the two, though.\n>\nI asked because the man page does indicae that it (A..B) is a special sort \nof revison range and \"there is a shorthand for it\", but then didn't have a \nway of naming it.\n\nThe symmetric difference is then brought in as a further similar notation. \nThere are a number of Stackoverflow questions about the differences betwee \n'two dots' and 'three dots' as well, so having a word/phrase for it could \nhelp.\n\nI was thinking that maybe \"single-sided difference (two dots)\" maybe one \nchoice that is relatively neutral (or even a \"two-dot range\"...).\n\n--\nPhilip \n\n"},{"id":"290145","messageId":"20160625164654.5192-3-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160625164654.5192-1-philipoakley@iee.org","subject":"[PATCH 2/2] doc: give headings for the two and three dot notations","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-06-25T16:46:54Z","receivedAt":"2016-06-25T16:47:12Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"While there, also break out the other shorthand notations and\nadd a title for the revision range summary (which also appears\nin git-rev-parse).\n\nSigned-off-by: Philip Oakley \n---\n Documentation/revisions.txt | 17 +++++++++++++----\n 1 file changed, 13 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 19314e3..c7e123a 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -246,12 +246,16 @@ To exclude commits reachable from a commit, a prefix '{caret}'\n notation is used. E.g. '{caret}r1 r2' means commits reachable\n from 'r2' but exclude the ones reachable from 'r1'.\n \n+Single-Sided Difference (two dots)\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n This set operation appears so often that there is a shorthand\n for it. When you have two commits 'r1' and 'r2' (named according\n to the syntax explained in SPECIFYING REVISIONS above), you can ask\n for commits that are reachable from r2 excluding those that are reachable\n from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.\n \n+Symmetric Difference (three dots)\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n A similar notation 'r1\\...r2' is called symmetric difference\n of 'r1' and 'r2' and is defined as\n 'r1 r2 --not $(git merge-base --all r1 r2)'.\n@@ -265,12 +269,17 @@ is a shorthand for 'HEAD..origin' and asks \"What did the origin do since\n I forked from them?\" Note that '..' would mean 'HEAD..HEAD' which is an\n empty range that is both reachable and unreachable from HEAD.\n \n+The '{caret}' Shorthands\n+~~~~~~~~~~~~~~~~~~~~~~~~\n Two other shorthands for naming a set that is formed by a commit\n-and its parent commits exist. The 'r1{caret}@' notation means all\n-parents of 'r1'. 'r1{caret}!' includes commit 'r1' but excludes\n-all of its parents.\n+and its parent commits exist.\n \n-To summarize:\n+The 'r1{caret}@' notation means all parents of 'r1'.\n+\n+'r1{caret}!' includes commit 'r1' but excludes all of its parents.\n+\n+Revision Range Summary\n+----------------------\n \n ''::\n \tInclude commits that are reachable from (i.e. ancestors of)\n-- \n2.8.4.windows.1.3.ge328a54\n\n"},{"id":"290146","messageId":"20160625164654.5192-2-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160625164654.5192-1-philipoakley@iee.org","subject":"[PATCH 1/2] doc: use 'symmetric difference' consistently","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-06-25T16:46:53Z","receivedAt":"2016-06-25T16:47:15Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Signed-off-by: Philip Oakley \n---\n Documentation/gitk.txt | 2 +-\n Documentation/rev-list-options.txt | 4 ++--\n 2 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/gitk.txt b/Documentation/gitk.txt\nindex 6ade002..6c3eb15 100644\n--- a/Documentation/gitk.txt\n+++ b/Documentation/gitk.txt\n@@ -70,7 +70,7 @@ linkgit:git-rev-list[1] for a complete list.\n \n --left-right::\n \n-\tMark which side of a symmetric diff a commit is reachable\n+\tMark which side of a symmetric difference a commit is reachable\n \tfrom. Commits from the left side are prefixed with a `<`\n \tsymbol and those from the right with a `>` symbol.\n \ndiff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt\nindex 4f009d4..6dc0bb0 100644\n--- a/Documentation/rev-list-options.txt\n+++ b/Documentation/rev-list-options.txt\n@@ -225,7 +225,7 @@ excluded from the output.\n \n --left-only::\n --right-only::\n-\tList only commits on the respective side of a symmetric range,\n+\tList only commits on the respective side of a symmetric difference,\n \ti.e. only those which would be marked `<` resp. `>` by\n \t`--left-right`.\n +\n@@ -766,7 +766,7 @@ ifdef::git-rev-list[]\n endif::git-rev-list[]\n \n --left-right::\n-\tMark which side of a symmetric diff a commit is reachable from.\n+\tMark which side of a symmetric difference a commit is reachable from.\n \tCommits from the left side are prefixed with `<` and those from\n \tthe right with `>`. If combined with `--boundary`, those\n \tcommits are prefixed with `-`.\n-- \n2.8.4.windows.1.3.ge328a54\n\n"},{"id":"290147","messageId":"20160625164654.5192-1-philipoakley@iee.org","threadId":"42687","inReplyTo":"E61B46FFA8874DD3973AA96BE5B36790@PhilipOakley","subject":"[PATCH 0/2] Re: name for A..B ranges?","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-06-25T16:46:52Z","receivedAt":"2016-06-25T16:47:18Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":">> On Wed, Jun 22, 2016 at 08:25:59AM +0100, Philip Oakley wrote:\n>>\n>>> Is there a common name for the A..B range format (two dots) that would\n>>> complement the A...B (three dots) symmetric range format's name?\n$gmane/297908\n\nHere is a short two patch series to hopefully enhance the\nrevisions (and rev-parse) man page to help clarify the symmetric\ndifference and two / three dots notations.\n\nThe HTML versions look OK to me - tested on the Git-for-Windows SDK.\n\nPhilip Oakley (2):\n doc: use 'symmetric difference' consistently\n doc: give headings for the two and three dot notations\n\n Documentation/gitk.txt | 2 +-\n Documentation/rev-list-options.txt | 4 ++--\n Documentation/revisions.txt | 17 +++++++++++++----\n 3 files changed, 16 insertions(+), 7 deletions(-)\n\n-- \n2.8.4.windows.1.3.ge328a54\n"},{"id":"290148","messageId":"20160625184702.4796-1-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160625164654.5192-1-philipoakley@iee.org","subject":"[PATCH] doc: show the actual left, right, and boundary marks","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-06-25T18:47:02Z","receivedAt":"2016-06-25T18:47:16Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Signed-off-by: Philip Oakley \n---\nThis is a quick follow on to the 'symmetric difference' documentation patches\nhttp://thread.gmane.org/gmane.comp.version-control.git/297908/focus=298223\nwhere I checked all the uses of 'left' to see if other terms had been used.\n\nI noticed that the actual marks were not being shown here, leaving the reader\nwith a difficult seach.\n\n\n---\n Documentation/pretty-formats.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt\nindex 29b19b9..10719e1 100644\n--- a/Documentation/pretty-formats.txt\n+++ b/Documentation/pretty-formats.txt\n@@ -166,7 +166,7 @@ endif::git-rev-list[]\n respecting the `auto` settings of the former if we are going to a\n terminal). `auto` alone (i.e. `%C(auto)`) will turn on auto coloring\n on the next placeholders until the color is switched again.\n-- '%m': left, right or boundary mark\n+- '%m': left (`<`), right (`>`) or boundary (`-`) mark\n - '%n': newline\n - '%%': a raw '%'\n - '%x00': print a byte from a hex code\n-- \n2.8.4.windows.1.3.ge328a54\n\n"},{"id":"290151","messageId":"xmqqwpldcamb.fsf@gitster.mtv.corp.google.com","threadId":"42687","inReplyTo":"E61B46FFA8874DD3973AA96BE5B36790@PhilipOakley","subject":"Re: name for A..B ranges?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-06-25T19:49:16Z","receivedAt":"2016-06-25T19:49:24Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" writes:\n\n>> Yup, I think \"range\" is the commonly used word in discussions here.\n>> When inventing A...B as a new thing in addition to A..B, we called\n>> the former \"symmetric difference\", and what is implied by that is\n>> the latter is \"asymmetric difference\"; we do not say that unless we\n>> are contrasting between the two, though.\n>>\n> I asked because the man page does indicae that it (A..B) is a special\n> sort of revison range and \"there is a shorthand for it\", but then\n> didn't have a way of naming it.\n\nI do not see \"is a special sort of revision range\" improved in your\ntwo patches, though.\n\nKnowing that A..B is merely a short-hand for ^A B is important to\nunderstand how revision ranges work (e.g. \"A..B C\" is not \"union of\nA..B and C\"), so I think it is worth addressing if the existing\ndescription appeared to you that it may confuse readers.\n\n> The symmetric difference is then brought in as a further similar\n> notation. There are a number of Stackoverflow questions about the\n> differences betwee 'two dots' and 'three dots' as well, so having a\n> word/phrase for it could help.\n>\n> I was thinking that maybe \"single-sided difference (two dots)\" maybe\n> one choice that is relatively neutral (or even a \"two-dot range\"...).\n\nWhen contrasting .. and ..., we have always used \"asymmetric\" vs\n\"symmetric\". I'd prefer to see usnot invent new phrase nobody has\nused, which leads to unnecessary confusion and learning burden.\n"},{"id":"290233","messageId":"8001594309A04A42859024BAEB8FF188@PhilipOakley","threadId":"42687","inReplyTo":"xmqqwpldcamb.fsf@gitster.mtv.corp.google.com","subject":"Re: name for A..B ranges?","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-06-27T13:37:35Z","receivedAt":"2016-06-27T13:37:44Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \n> \"Philip Oakley\" writes:\n>\n>>> Yup, I think \"range\" is the commonly used word in discussions here.\n>>> When inventing A...B as a new thing in addition to A..B, we called\n>>> the former \"symmetric difference\", and what is implied by that is\n>>> the latter is \"asymmetric difference\"; we do not say that unless we\n>>> are contrasting between the two, though.\n>>>\n>> I asked because the man page does indicae that it (A..B) is a special\n>> sort of revison range and \"there is a shorthand for it\", but then\n>> didn't have a way of naming it.\n>\n> I do not see \"is a special sort of revision range\" improved in your\n> two patches, though.\n\nHi Junio\n\nI'm not sure what's meant here. That patch was about ensuring that the \nrelevant syntax notations had headings to make them more easily locatable, \nnot to change the explanations.\n\n>\n> Knowing that A..B is merely a short-hand for ^A B is important to\n> understand how revision ranges work (e.g. \"A..B C\" is not \"union of\n> A..B and C\"), so I think it is worth addressing if the existing\n> description appeared to you that it may confuse readers.\n\nI felt the explanations, once found, were OK. It was the discovery step I \nwas hoepfully addressing.\n>\n>> The symmetric difference is then brought in as a further similar\n>> notation. There are a number of Stackoverflow questions about the\n>> differences betwee 'two dots' and 'three dots' as well, so having a\n>> word/phrase for it could help.\n>>\n>> I was thinking that maybe \"single-sided difference (two dots)\" maybe\n>> one choice that is relatively neutral (or even a \"two-dot range\"...).\n>\n> When contrasting .. and ..., we have always used \"asymmetric\" vs\n> \"symmetric\". I'd prefer to see usnot invent new phrase nobody has\n> used, which leads to unnecessary confusion and learning burden.\n\nRather than trying to find a complement to the previously invented \n\"symmetric difference\" name (for the section heading), I was wondering if an \nalternative would be to refer to it via [use the headings of] it's notation, \ni.e. \"the 'two-dot' range notation\" (or 'syntax' is that is preferred), and \nthe \"three-dot symmetric difference notation\".\n\nThe existing explanatory text can stand as is, but they would now have a \nsection for readers to find.\n\nOr should I just drop this?\n\n--\nPhilip\n\n"},{"id":"290238","messageId":"xmqq4m8ed5zu.fsf@gitster.mtv.corp.google.com","threadId":"42687","inReplyTo":"8001594309A04A42859024BAEB8FF188@PhilipOakley","subject":"Re: name for A..B ranges?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-06-27T15:08:21Z","receivedAt":"2016-06-27T15:08:29Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" writes:\n\n> ..., I was wondering\n> if an alternative would be to refer to it via [use the headings of]\n> it's notation, i.e. \"the 'two-dot' range notation\" (or 'syntax' is\n> that is preferred), and the \"three-dot symmetric difference notation\".\n\nThat's a lot more sensible pair of headings, I would think.\n\n> The existing explanatory text can stand as is, but they would now have\n> a section for readers to find.\n>\n> Or should I just drop this?\n\nI like the approach to separate them into clearly marked sections.\nI primarily was reacting to the \"single-sided\" which nobody would\nunderstand.\n"},{"id":"290240","messageId":"276137126E354C29A6F472556B76B3D6@PhilipOakley","threadId":"42687","inReplyTo":"xmqq4m8ed5zu.fsf@gitster.mtv.corp.google.com","subject":"Re: name for A..B ranges?","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-06-27T15:39:19Z","receivedAt":"2016-06-27T15:39:43Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \n> \"Philip Oakley\" writes:\n> \n>> ..., I was wondering\n>> if an alternative would be to refer to it via [use the headings of]\n>> it's notation, i.e. \"the 'two-dot' range notation\" (or 'syntax' is\n>> that is preferred), and the \"three-dot symmetric difference notation\".\n> \n> That's a lot more sensible pair of headings, I would think.\n> \n>> The existing explanatory text can stand as is, but they would now have\n>> a section for readers to find.\n>>\n>> Or should I just drop this?\n> \n> I like the approach to separate them into clearly marked sections.\n> I primarily was reacting to the \"single-sided\" which nobody would\n> understand.\n> --\n\nThanks, I'll update the patches (probably tomorrow)\nPhilip\n"},{"id":"290611","messageId":"20160630202509.4472-2-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160630202509.4472-1-philipoakley@iee.org","subject":"[PATCH v2 1/4] doc: use 'symmetric difference' consistently","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-06-30T20:25:06Z","receivedAt":"2016-06-30T20:41:25Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Signed-off-by: Philip Oakley \n---\n Documentation/gitk.txt | 2 +-\n Documentation/rev-list-options.txt | 4 ++--\n 2 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/gitk.txt b/Documentation/gitk.txt\nindex 6ade002..6c3eb15 100644\n--- a/Documentation/gitk.txt\n+++ b/Documentation/gitk.txt\n@@ -70,7 +70,7 @@ linkgit:git-rev-list[1] for a complete list.\n \n --left-right::\n \n-\tMark which side of a symmetric diff a commit is reachable\n+\tMark which side of a symmetric difference a commit is reachable\n \tfrom. Commits from the left side are prefixed with a `<`\n \tsymbol and those from the right with a `>` symbol.\n \ndiff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt\nindex 4f009d4..6dc0bb0 100644\n--- a/Documentation/rev-list-options.txt\n+++ b/Documentation/rev-list-options.txt\n@@ -225,7 +225,7 @@ excluded from the output.\n \n --left-only::\n --right-only::\n-\tList only commits on the respective side of a symmetric range,\n+\tList only commits on the respective side of a symmetric difference,\n \ti.e. only those which would be marked `<` resp. `>` by\n \t`--left-right`.\n +\n@@ -766,7 +766,7 @@ ifdef::git-rev-list[]\n endif::git-rev-list[]\n \n --left-right::\n-\tMark which side of a symmetric diff a commit is reachable from.\n+\tMark which side of a symmetric difference a commit is reachable from.\n \tCommits from the left side are prefixed with `<` and those from\n \tthe right with `>`. If combined with `--boundary`, those\n \tcommits are prefixed with `-`.\n-- \n2.8.4.windows.1.3.ge328a54\n\n"},{"id":"290612","messageId":"20160630202509.4472-4-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160630202509.4472-1-philipoakley@iee.org","subject":"[PATCH v2 3/4] doc: give headings for the two and three dot notations","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-06-30T20:25:08Z","receivedAt":"2016-06-30T20:41:33Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"While there, also break out the other shorthand notations and\nadd a title for the revision range summary (which also appears\nin git-rev-parse, so keep it mixed case).\n\nSigned-off-by: Philip Oakley \n---\n Documentation/revisions.txt | 23 +++++++++++++++++------\n 1 file changed, 17 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 19314e3..131060c 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -242,35 +242,46 @@ specifying a single revision with the notation described in the\n previous section means the set of commits reachable from that\n commit, following the commit ancestry chain.\n \n+The '{caret}' (caret) notation\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n To exclude commits reachable from a commit, a prefix '{caret}'\n notation is used. E.g. '{caret}r1 r2' means commits reachable\n from 'r2' but exclude the ones reachable from 'r1'.\n \n-This set operation appears so often that there is a shorthand\n+The '..' (two-dot) range notation\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+The '{caret}r1 r2' set operation appears so often that there is a shorthand\n for it. When you have two commits 'r1' and 'r2' (named according\n to the syntax explained in SPECIFYING REVISIONS above), you can ask\n for commits that are reachable from r2 excluding those that are reachable\n from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.\n \n+The '...' (three dot) Symmetric Difference notation\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n A similar notation 'r1\\...r2' is called symmetric difference\n of 'r1' and 'r2' and is defined as\n 'r1 r2 --not $(git merge-base --all r1 r2)'.\n It is the set of commits that are reachable from either one of\n 'r1' or 'r2' but not from both.\n \n-In these two shorthands, you can omit one end and let it default to HEAD.\n+In these two shorthand notations, you can omit one end and let it default to HEAD.\n For example, 'origin..' is a shorthand for 'origin..HEAD' and asks \"What\n did I do since I forked from the origin branch?\" Similarly, '..origin'\n is a shorthand for 'HEAD..origin' and asks \"What did the origin do since\n I forked from them?\" Note that '..' would mean 'HEAD..HEAD' which is an\n empty range that is both reachable and unreachable from HEAD.\n \n+Additional '{caret}' Shorthand notations\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n Two other shorthands for naming a set that is formed by a commit\n-and its parent commits exist. The 'r1{caret}@' notation means all\n-parents of 'r1'. 'r1{caret}!' includes commit 'r1' but excludes\n-all of its parents.\n+and its parent commits exist.\n \n-To summarize:\n+The 'r1{caret}@' notation means all parents of 'r1'.\n+\n+'r1{caret}!' includes commit 'r1' but excludes all of its parents.\n+\n+Revision Range Summary\n+----------------------\n \n ''::\n \tInclude commits that are reachable from (i.e. ancestors of)\n-- \n2.8.4.windows.1.3.ge328a54\n\n"},{"id":"290613","messageId":"20160630202509.4472-1-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160625164654.5192-1-philipoakley@iee.org","subject":"[PATCH v2 0/4] Name for A..B ranges?","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-06-30T20:25:05Z","receivedAt":"2016-06-30T20:41:34Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"This is the re-roll of the po/range-doc (2016-06-27) 3 commits\n\nThe order is slightly re-arranged, and an additional patch clarifying\nthat ^r1 excludes r1 itself being added.\n\nThe heading have been tweaked.\n\nDiscussion: $gmane/297908\nprevious patch series $gmane/298223\n\nPhilip Oakley (4):\n doc: use 'symmetric difference' consistently\n doc: show the actual left, right, and boundary marks\n doc: give headings for the two and three dot notations\n doc: clarify that `^r1` will exclude `r1` itself\n\n Documentation/gitk.txt | 2 +-\n Documentation/pretty-formats.txt | 2 +-\n Documentation/rev-list-options.txt | 4 ++--\n Documentation/revisions.txt | 25 ++++++++++++++++++-------\n 4 files changed, 22 insertions(+), 11 deletions(-)\n\n-- \n2.8.4.windows.1.3.ge328a54\n\n"},{"id":"290614","messageId":"20160630202509.4472-5-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160630202509.4472-1-philipoakley@iee.org","subject":"[PATCH v2 4/4] doc: clarify that `^r1` will exclude `r1` itself","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-06-30T20:25:09Z","receivedAt":"2016-06-30T20:42:11Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Signed-off-by: Philip Oakley \n---\n Documentation/revisions.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 131060c..87be9c4 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -246,7 +246,7 @@ The '{caret}' (caret) notation\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n To exclude commits reachable from a commit, a prefix '{caret}'\n notation is used. E.g. '{caret}r1 r2' means commits reachable\n-from 'r2' but exclude the ones reachable from 'r1'.\n+from 'r2' but exclude 'r1' and those reachable from 'r1'.\n \n The '..' (two-dot) range notation\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n-- \n2.8.4.windows.1.3.ge328a54\n\n"},{"id":"290615","messageId":"20160630202509.4472-3-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160630202509.4472-1-philipoakley@iee.org","subject":"[PATCH v2 2/4] doc: show the actual left, right, and boundary marks","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-06-30T20:25:07Z","receivedAt":"2016-06-30T20:42:19Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Signed-off-by: Philip Oakley \n---\nFound while checking the 'symmetric difference' documentation\n---\n Documentation/pretty-formats.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt\nindex 29b19b9..10719e1 100644\n--- a/Documentation/pretty-formats.txt\n+++ b/Documentation/pretty-formats.txt\n@@ -166,7 +166,7 @@ endif::git-rev-list[]\n respecting the `auto` settings of the former if we are going to a\n terminal). `auto` alone (i.e. `%C(auto)`) will turn on auto coloring\n on the next placeholders until the color is switched again.\n-- '%m': left, right or boundary mark\n+- '%m': left (`<`), right (`>`) or boundary (`-`) mark\n - '%n': newline\n - '%%': a raw '%'\n - '%x00': print a byte from a hex code\n-- \n2.8.4.windows.1.3.ge328a54\n\n"},{"id":"290713","messageId":"xmqqk2h5vz2m.fsf@gitster.mtv.corp.google.com","threadId":"42687","inReplyTo":"20160630202509.4472-5-philipoakley@iee.org","subject":"Re: [PATCH v2 4/4] doc: clarify that `^r1` will exclude `r1` itself","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-07-01T21:16:33Z","receivedAt":"2016-07-01T21:16:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley writes:\n\n> Signed-off-by: Philip Oakley \n> ---\n> Documentation/revisions.txt | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\n> index 131060c..87be9c4 100644\n> --- a/Documentation/revisions.txt\n> +++ b/Documentation/revisions.txt\n> @@ -246,7 +246,7 @@ The '{caret}' (caret) notation\n> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n> To exclude commits reachable from a commit, a prefix '{caret}'\n> notation is used. E.g. '{caret}r1 r2' means commits reachable\n> -from 'r2' but exclude the ones reachable from 'r1'.\n> +from 'r2' but exclude 'r1' and those reachable from 'r1'.\n\nWell, if you have to spell that out, you'd want to spell out r2 side\ntoo, no? That is,\n\n\t... means commits 'r2' and those reachable from 'r2', but\n\texclude 'r1' and those reachable from 'r1'.\n\nThe (sub)document has 16 grep hits of \"reach(able)\"; a reader who\nneeds this clarification would need all of them clarified, but\nrepeating \"X and those reachable from X\" everywhere is not a good\nway to do so. Perhaps a separate sentence upfront that defines what\n\"reachable\" means is a better solution, no?\n\nSomething like the attached patch may be a good starting point, but\nthis leaves two forward-references of reachable in the part that\ndescribes ways to specify a single object (e.g. find a commit with\nthis string that is reachable by X) we may need to address, perhaps\nby adding \"(see below)\" or something.\n\n\n Documentation/revisions.txt | 4 ++++\n 1 file changed, 4 insertions(+)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 19314e3..34642b9 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -242,6 +242,10 @@ specifying a single revision with the notation described in the\n previous section means the set of commits reachable from that\n commit, following the commit ancestry chain.\n \n+A commit Y is said to be reachable from commit X if Y is X, or if Y\n+is reachable from any any of X's parents. We also say \"Y is an\n+ancestor of X\" in such a case.\n+\n To exclude commits reachable from a commit, a prefix '{caret}'\n notation is used. E.g. '{caret}r1 r2' means commits reachable\n from 'r2' but exclude the ones reachable from 'r1'.\n\n\n"},{"id":"290714","messageId":"xmqqd1mxvyka.fsf@gitster.mtv.corp.google.com","threadId":"42687","inReplyTo":"20160630202509.4472-1-philipoakley@iee.org","subject":"Re: [PATCH v2 0/4] Name for A..B ranges?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-07-01T21:27:33Z","receivedAt":"2016-07-01T21:27:58Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley writes:\n\n> This is the re-roll of the po/range-doc (2016-06-27) 3 commits\n>\n> The order is slightly re-arranged, and an additional patch clarifying\n> that ^r1 excludes r1 itself being added.\n>\n> The heading have been tweaked.\n\nThanks.\n\nI think 1-3 are ready for 'next'. 4/4 may need a bit more\nthinking.\n\n"},{"id":"290717","messageId":"CAPc5daW_Kf8UG2zm4vBS9f4tN+bXusdZQkcwnssNs+gdk8J75w@mail.gmail.com","threadId":"42687","inReplyTo":"38FAE374CD2D44EC9C86167F98953271@PhilipOakley","subject":"Re: [PATCH v2 4/4] doc: clarify that `^r1` will exclude `r1` itself","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-07-01T22:14:40Z","receivedAt":"2016-07-01T22:20:41Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"On Fri, Jul 1, 2016 at 3:08 PM, Philip Oakley wrote:\n>>> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n>>> To exclude commits reachable from a commit, a prefix '{caret}'\n>>> notation is used. E.g. '{caret}r1 r2' means commits reachable\n>>> -from 'r2' but exclude the ones reachable from 'r1'.\n>>> +from 'r2' but exclude 'r1' and those reachable from 'r1'.\n>>\n>> Well, if you have to spell that out, you'd want to spell out r2 side\n>> too, no? That is,\n>\n> The clarification wasn't about what \"reachable\" means but about inclusivity,\n> such as whether 0..4 would give 0,1,2,3,4 or would be 'off by one' and only\n> give 1,2,3,4. And in this case it's the latter.\n\nWell, you have the same inclusivity issue on the opposite end, no? Is 0..4\na range with 0,1,2,3,4? 0,1,2,3? 1,2,3,4? or 1,2,3?\n\n> Describing 'reachability' is a whole different kettle of fish, as you\n> highlight below, and would be separate from this patch.\n\nI am not sure I agree. It all is about \"is the endpoint included or not?\".\n"},{"id":"290718","messageId":"38FAE374CD2D44EC9C86167F98953271@PhilipOakley","threadId":"42687","inReplyTo":"xmqqk2h5vz2m.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH v2 4/4] doc: clarify that `^r1` will exclude `r1` itself","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-07-01T22:08:24Z","receivedAt":"2016-07-01T22:21:11Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \n> Philip Oakley writes:\n>\n>> Signed-off-by: Philip Oakley \n>> ---\n>> Documentation/revisions.txt | 2 +-\n>> 1 file changed, 1 insertion(+), 1 deletion(-)\n>>\n>> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\n>> index 131060c..87be9c4 100644\n>> --- a/Documentation/revisions.txt\n>> +++ b/Documentation/revisions.txt\n>> @@ -246,7 +246,7 @@ The '{caret}' (caret) notation\n>> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n>> To exclude commits reachable from a commit, a prefix '{caret}'\n>> notation is used. E.g. '{caret}r1 r2' means commits reachable\n>> -from 'r2' but exclude the ones reachable from 'r1'.\n>> +from 'r2' but exclude 'r1' and those reachable from 'r1'.\n>\n> Well, if you have to spell that out, you'd want to spell out r2 side\n> too, no? That is,\n\nThe clarification wasn't about what \"reachable\" means but about inclusivity,\nsuch as whether 0..4 would give 0,1,2,3,4 or would be 'off by one' and only\ngive 1,2,3,4. And in this case it's the latter.\n\nDescribing 'reachability' is a whole different kettle of fish, as you\nhighlight below, and would be separate from this patch.\n\nI've certainly tripped up in the past over using an appropriate reachability\ndefinition in r1..r2, and forgetting (*) about remote branches being in the\nlocal graph . (*- i.e. not really understanding!)\n\n--\nPhilip\n(only occasional access to internet over next few days)\n>\n> ... means commits 'r2' and those reachable from 'r2', but\n> exclude 'r1' and those reachable from 'r1'.\n>\n> The (sub)document has 16 grep hits of \"reach(able)\"; a reader who\n> needs this clarification would need all of them clarified, but\n> repeating \"X and those reachable from X\" everywhere is not a good\n> way to do so. Perhaps a separate sentence upfront that defines what\n> \"reachable\" means is a better solution, no?\n>\n> Something like the attached patch may be a good starting point, but\n> this leaves two forward-references of reachable in the part that\n> describes ways to specify a single object (e.g. find a commit with\n> this string that is reachable by X) we may need to address, perhaps\n> by adding \"(see below)\" or something.\n>\n>\n> Documentation/revisions.txt | 4 ++++\n> 1 file changed, 4 insertions(+)\n>\n> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\n> index 19314e3..34642b9 100644\n> --- a/Documentation/revisions.txt\n> +++ b/Documentation/revisions.txt\n> @@ -242,6 +242,10 @@ specifying a single revision with the notation\n> described in the\n> previous section means the set of commits reachable from that\n> commit, following the commit ancestry chain.\n>\n> +A commit Y is said to be reachable from commit X if Y is X, or if Y\n> +is reachable from any any of X's parents. We also say \"Y is an\n> +ancestor of X\" in such a case.\n> +\n> To exclude commits reachable from a commit, a prefix '{caret}'\n> notation is used. E.g. '{caret}r1 r2' means commits reachable\n> from 'r2' but exclude the ones reachable from 'r1'.\n>\n> \n\n"},{"id":"290721","messageId":"xmqqziq1ufmk.fsf@gitster.mtv.corp.google.com","threadId":"42687","inReplyTo":"CAPc5daW_Kf8UG2zm4vBS9f4tN+bXusdZQkcwnssNs+gdk8J75w@mail.gmail.com","subject":"Re: [PATCH v2 4/4] doc: clarify that `^r1` will exclude `r1` itself","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-07-01T23:01:55Z","receivedAt":"2016-07-01T23:02:16Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> On Fri, Jul 1, 2016 at 3:08 PM, Philip Oakley wrote:\n>>>> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n>>>> To exclude commits reachable from a commit, a prefix '{caret}'\n>>>> notation is used. E.g. '{caret}r1 r2' means commits reachable\n>>>> -from 'r2' but exclude the ones reachable from 'r1'.\n>>>> +from 'r2' but exclude 'r1' and those reachable from 'r1'.\n>>>\n>>> Well, if you have to spell that out, you'd want to spell out r2 side\n>>> too, no? That is,\n>>\n>> The clarification wasn't about what \"reachable\" means but about inclusivity,\n>> such as whether 0..4 would give 0,1,2,3,4 or would be 'off by one' and only\n>> give 1,2,3,4. And in this case it's the latter.\n>\n> Well, you have the same inclusivity issue on the opposite end, no? Is 0..4\n> a range with 0,1,2,3,4? 0,1,2,3? 1,2,3,4? or 1,2,3?\n>\n>> Describing 'reachability' is a whole different kettle of fish, as you\n>> highlight below, and would be separate from this patch.\n>\n> I am not sure I agree. It all is about \"is the endpoint included or not?\".\n\nThis did not come out as illustrating as I hoped. Let's put it\ndifferently.\n\nI think this is all about how \"reachable\" is defined. \"Am I an\nancestor of myself?\" is the question.\n\nIf \"all commits reachable from r1\" includes 'r1', then, it is clear\nthat \"... but exclude those reachable from 'r1'\" means 'r1' is not\npart of the resulting set.\n\nIf I were not an ancestor of me, on the other hand, \"... but exclude\nthose who are ancestors of 'r1'\" would not exclude 'r1'. If 'r1' is\nreachable from 'r2', then 'r1' would be in the resulting set.\n\nThe same thing happens at the opposite end of the \"range\". If I am\nan ancestor of me, then \"all commits reachable from 'r2'\" does\ninculde 'r2'; if I am not an ancestor of me, 'r2' is not part of the\nresulting set.\n\n\tNote. I said \"range\" in quotes, because this is not like\n\tdrawing a straight line and placing two points to denote the\n\tlower and the upper bounds of the \"range\". What Git does is\n\ta set operation, \"r2 ^r1\" excludes what is reachable from r1\n from the set of commits that are reachable from r2.\n\nBy choosing the definition of \"reachable\" consistently, 0..4 can\nmean either 1,2,3,4 (I am reachable from myself) or 0,1,2,3 (I can\nnot be reached by me), and in order to clarify that we give 1,2,3,4\nand not 0,1,2,3, we still need to clearly define what \"reachable\"\nmeans.\n\nBut any other interpretation, e.g. 0,1,2,3,4, is incoherent.\n"},{"id":"291148","messageId":"A584078D859245AABA92ADC75B82A77A@PhilipOakley","threadId":"42687","inReplyTo":"xmqqziq1ufmk.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH v2 4/4] doc: clarify that `^r1` will exclude `r1` itself","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-07-10T21:17:56Z","receivedAt":"2016-07-10T21:18:03Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" : Saturday, July 02, 2016 12:01 \nAM\n> Junio C Hamano writes:\n>\n>> On Fri, Jul 1, 2016 at 3:08 PM, Philip Oakley \n>> wrote:\n>>>>> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n>>>>> To exclude commits reachable from a commit, a prefix '{caret}'\n>>>>> notation is used. E.g. '{caret}r1 r2' means commits reachable\n>>>>> -from 'r2' but exclude the ones reachable from 'r1'.\n>>>>> +from 'r2' but exclude 'r1' and those reachable from 'r1'.\nHi Junio\nSorry for the delay in response, I'd been away and had some catch up to do.\n\nI think we may have dropped into a YXproblem.\n\nMy particular concern was the literary conflict between the implicit \n'inclusive' aspects and the explicit 'exclusive' parts of the descriptions, \na sort of barber shaving problem [1], especially when used in conjunction \nwith the negation.\n\nIt's the potential for reader confusion at that point (particularly for a \nstring of pearls case) I was trying to address. However, you are right that \n'reachable' also isn't as well defined as it might be.\n\nFor example, in a DAG, we should have no cycles where directed edges lead \ncan back to their start point, yet (for reachability discussions) we want to \nimply an extra loopback edge, all of which is part of the sloppiness of \nnatural languages.\n\nThis potential for confusion is further shown in the summary where both \n and ^ say \"(i.e. ancestors of)\"!\n\nIn summary, I think that both the definition of reachability needs \nclarifying, and that c0ffee..deadbeef excludes any serving of c0ffee, even \nfor a line of pearls, should be covered.\n\n>>>>\n>>>> Well, if you have to spell that out, you'd want to spell out r2 side\n>>>> too, no? That is,\n>>>\n>>> The clarification wasn't about what \"reachable\" means but about \n>>> inclusivity,\n>>> such as whether 0..4 would give 0,1,2,3,4 or would be 'off by one' and \n>>> only\n>>> give 1,2,3,4. And in this case it's the latter.\n>>\n>> Well, you have the same inclusivity issue on the opposite end, no? Is \n>> 0..4\n>> a range with 0,1,2,3,4? 0,1,2,3? 1,2,3,4? or 1,2,3?\n\nIn most natural language we have 0:4 is 0,1,2,3,4 so the exclusion of 0 \nwould be the one to note.\n\n>>\n>>> Describing 'reachability' is a whole different kettle of fish, as you\n>>> highlight below, and would be separate from this patch.\nsee below.\n\n>>\n>> I am not sure I agree. It all is about \"is the endpoint included or \n>> not?\".\n>\n> This did not come out as illustrating as I hoped. Let's put it\n> differently.\n>\n> I think this is all about how \"reachable\" is defined. \"Am I an\n> ancestor of myself?\" is the question.\n\nI don't think that just clarifying \"reachability\" would be sufficient. \nNecessary yes, sufficient no.\n\n>\n> If \"all commits reachable from r1\" includes 'r1', then, it is clear\n> that \"... but exclude those reachable from 'r1'\" means 'r1' is not\n> part of the resulting set.\n>\n> If I were not an ancestor of me, on the other hand, \"... but exclude\n> those who are ancestors of 'r1'\" would not exclude 'r1'. If 'r1' is\n> reachable from 'r2', then 'r1' would be in the resulting set.\n>\n> The same thing happens at the opposite end of the \"range\". If I am\n> an ancestor of me, then \"all commits reachable from 'r2'\" does\n> inculde 'r2'; if I am not an ancestor of me, 'r2' is not part of the\n> resulting set.\n>\n\n> Note.\n> I said \"range\" in quotes, because this is not like\n> drawing a straight line and placing two points to denote the\n> lower and the upper bounds of the \"range\". What Git does is\n> a set operation, \"r2 ^r1\" excludes what is reachable from r1\n> from the set of commits that are reachable from r2.\n\nThe understanding of this \"Y\" branching \"range\" is the part that was the \n'whole new kettle of fish' for me, especially with the rtbs, that caught me \nout during early contributions.\n\n\n>\n> By choosing the definition of \"reachable\" consistently, 0..4 can\n> mean either 1,2,3,4 (I am reachable from myself) or 0,1,2,3 (I can\n> not be reached by me), and in order to clarify that we give 1,2,3,4\n> and not 0,1,2,3, we still need to clearly define what \"reachable\"\n> means.\n\nI'll re-think the patch (4/4) to cover thse issue.\n\n>\n> But any other interpretation, e.g. 0,1,2,3,4, is incoherent.\n> --\nPhilip\n\n[1] https://en.wikipedia.org/wiki/Barber_paradox \n\n"},{"id":"291201","messageId":"20160711202518.532-2-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160711202518.532-1-philipoakley@iee.org","subject":"[PATCH v3 1/8] doc: use 'symmetric difference' consistently","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-07-11T20:25:11Z","receivedAt":"2016-07-11T20:25:32Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Signed-off-by: Philip Oakley \n---\n Documentation/gitk.txt | 2 +-\n Documentation/rev-list-options.txt | 4 ++--\n 2 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/gitk.txt b/Documentation/gitk.txt\nindex 6ade002..6c3eb15 100644\n--- a/Documentation/gitk.txt\n+++ b/Documentation/gitk.txt\n@@ -70,7 +70,7 @@ linkgit:git-rev-list[1] for a complete list.\n \n --left-right::\n \n-\tMark which side of a symmetric diff a commit is reachable\n+\tMark which side of a symmetric difference a commit is reachable\n \tfrom. Commits from the left side are prefixed with a `<`\n \tsymbol and those from the right with a `>` symbol.\n \ndiff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt\nindex 4f009d4..6dc0bb0 100644\n--- a/Documentation/rev-list-options.txt\n+++ b/Documentation/rev-list-options.txt\n@@ -225,7 +225,7 @@ excluded from the output.\n \n --left-only::\n --right-only::\n-\tList only commits on the respective side of a symmetric range,\n+\tList only commits on the respective side of a symmetric difference,\n \ti.e. only those which would be marked `<` resp. `>` by\n \t`--left-right`.\n +\n@@ -766,7 +766,7 @@ ifdef::git-rev-list[]\n endif::git-rev-list[]\n \n --left-right::\n-\tMark which side of a symmetric diff a commit is reachable from.\n+\tMark which side of a symmetric difference a commit is reachable from.\n \tCommits from the left side are prefixed with `<` and those from\n \tthe right with `>`. If combined with `--boundary`, those\n \tcommits are prefixed with `-`.\n-- \n2.8.4.windows.1.3.ge328a54\n\n"},{"id":"291202","messageId":"20160711202518.532-4-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160711202518.532-1-philipoakley@iee.org","subject":"[PATCH v3 3/8] doc: show the actual left, right, and boundary marks","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-07-11T20:25:13Z","receivedAt":"2016-07-11T20:25:37Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Signed-off-by: Philip Oakley \n---\nFound while checking the 'symmetric difference' documentation\n---\n Documentation/pretty-formats.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt\nindex 29b19b9..10719e1 100644\n--- a/Documentation/pretty-formats.txt\n+++ b/Documentation/pretty-formats.txt\n@@ -166,7 +166,7 @@ endif::git-rev-list[]\n respecting the `auto` settings of the former if we are going to a\n terminal). `auto` alone (i.e. `%C(auto)`) will turn on auto coloring\n on the next placeholders until the color is switched again.\n-- '%m': left, right or boundary mark\n+- '%m': left (`<`), right (`>`) or boundary (`-`) mark\n - '%n': newline\n - '%%': a raw '%'\n - '%x00': print a byte from a hex code\n-- \n2.8.4.windows.1.3.ge328a54\n\n"},{"id":"291203","messageId":"20160711202518.532-5-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160711202518.532-1-philipoakley@iee.org","subject":"[PATCH v3 4/8] doc: give headings for the two and three dot notations","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-07-11T20:25:14Z","receivedAt":"2016-07-11T20:25:40Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"While there, also break out the other shorthand notations and\nadd a title for the revision range summary (which also appears\nin git-rev-parse, so keep it mixed case).\n\nSigned-off-by: Philip Oakley \n---\n Documentation/revisions.txt | 23 +++++++++++++++++------\n 1 file changed, 17 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 79f6d03..1c59e87 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -242,35 +242,46 @@ specifying a single revision with the notation described in the\n previous section means the set of commits reachable from that\n commit, following the commit ancestry chain.\n \n+The '{caret}' (caret) notation\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n To exclude commits reachable from a commit, a prefix '{caret}'\n notation is used. E.g. '{caret}r1 r2' means commits reachable\n from 'r2' but exclude the ones reachable from 'r1'.\n \n-This set operation appears so often that there is a shorthand\n+The '..' (two-dot) range notation\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+The '{caret}r1 r2' set operation appears so often that there is a shorthand\n for it. When you have two commits 'r1' and 'r2' (named according\n to the syntax explained in SPECIFYING REVISIONS above), you can ask\n for commits that are reachable from r2 excluding those that are reachable\n from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.\n \n+The '...' (three dot) Symmetric Difference notation\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n A similar notation 'r1\\...r2' is called symmetric difference\n of 'r1' and 'r2' and is defined as\n 'r1 r2 --not $(git merge-base --all r1 r2)'.\n It is the set of commits that are reachable from either one of\n 'r1' (Left side) or 'r2' (Right side) but not from both.\n \n-In these two shorthands, you can omit one end and let it default to HEAD.\n+In these two shorthand notations, you can omit one end and let it default to HEAD.\n For example, 'origin..' is a shorthand for 'origin..HEAD' and asks \"What\n did I do since I forked from the origin branch?\" Similarly, '..origin'\n is a shorthand for 'HEAD..origin' and asks \"What did the origin do since\n I forked from them?\" Note that '..' would mean 'HEAD..HEAD' which is an\n empty range that is both reachable and unreachable from HEAD.\n \n+Additional '{caret}' Shorthand notations\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n Two other shorthands for naming a set that is formed by a commit\n-and its parent commits exist. The 'r1{caret}@' notation means all\n-parents of 'r1'. 'r1{caret}!' includes commit 'r1' but excludes\n-all of its parents.\n+and its parent commits exist.\n \n-To summarize:\n+The 'r1{caret}@' notation means all parents of 'r1'.\n+\n+'r1{caret}!' includes commit 'r1' but excludes all of its parents.\n+\n+Revision Range Summary\n+----------------------\n \n ''::\n \tInclude commits that are reachable from (i.e. ancestors of)\n-- \n2.8.4.windows.1.3.ge328a54\n\n"},{"id":"291204","messageId":"20160711202518.532-6-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160711202518.532-1-philipoakley@iee.org","subject":"[PATCH v3 5/8] doc: gitrevisions - use 'reachable' in page description","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-07-11T20:25:15Z","receivedAt":"2016-07-11T20:25:41Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Signed-off-by: Philip Oakley \n---\n Documentation/gitrevisions.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/gitrevisions.txt b/Documentation/gitrevisions.txt\nindex e903eb7..33039c6 100644\n--- a/Documentation/gitrevisions.txt\n+++ b/Documentation/gitrevisions.txt\n@@ -15,8 +15,8 @@ DESCRIPTION\n \n Many Git commands take revision parameters as arguments. Depending on\n the command, they denote a specific commit or, for commands which\n-walk the revision graph (such as linkgit:git-log[1]), all commits which can\n-be reached from that commit. In the latter case one can also specify a\n+walk the revision graph (such as linkgit:git-log[1]), all commits which are\n+reachable from that commit. In the latter case one can also specify a\n range of revisions explicitly.\n \n In addition, some Git commands (such as linkgit:git-show[1]) also take\n-- \n2.8.4.windows.1.3.ge328a54\n\n"},{"id":"291205","messageId":"20160711202518.532-7-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160711202518.532-1-philipoakley@iee.org","subject":"[PATCH v3 6/8] doc: gitrevisions - clarify 'latter case' is revision walk","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-07-11T20:25:16Z","receivedAt":"2016-07-11T20:25:44Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"The prior sentence has too many clauses for easy parsing.\nReplace 'the latter case' with a direct quote.\n\nSigned-off-by: Philip Oakley \n---\n Documentation/gitrevisions.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/gitrevisions.txt b/Documentation/gitrevisions.txt\nindex 33039c6..27dec5b 100644\n--- a/Documentation/gitrevisions.txt\n+++ b/Documentation/gitrevisions.txt\n@@ -16,8 +16,8 @@ DESCRIPTION\n Many Git commands take revision parameters as arguments. Depending on\n the command, they denote a specific commit or, for commands which\n walk the revision graph (such as linkgit:git-log[1]), all commits which are\n-reachable from that commit. In the latter case one can also specify a\n-range of revisions explicitly.\n+reachable from that commit. For commands that walk the revision graph one can\n+also specify a range of revisions explicitly.\n \n In addition, some Git commands (such as linkgit:git-show[1]) also take\n revision parameters which denote other objects than commits, e.g. blobs\n-- \n2.8.4.windows.1.3.ge328a54\n\n"},{"id":"291206","messageId":"20160711202518.532-8-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160711202518.532-1-philipoakley@iee.org","subject":"[PATCH v3 7/8] doc: revisions - define `reachable`","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-07-11T20:25:17Z","receivedAt":"2016-07-11T20:25:47Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Do not self-define `reachable`, which can lead to misunderstanding.\nInstead define `reachability` explictly.\n\nSigned-off-by: Philip Oakley \n---\n Documentation/revisions.txt | 14 ++++++++++----\n 1 file changed, 10 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 1c59e87..a3cd28b 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -237,10 +237,16 @@ SPECIFYING RANGES\n -----------------\n \n History traversing commands such as `git log` operate on a set\n-of commits, not just a single commit. To these commands,\n-specifying a single revision with the notation described in the\n-previous section means the set of commits reachable from that\n-commit, following the commit ancestry chain.\n+of commits, not just a single commit.\n+\n+For these commands,\n+specifying a single revision, using the notation described in the\n+previous section, means the `reachable` set of commits of the given\n+commit.\n+\n+A commit's reachable set is the commit itself and the commits of\n+its ancestry chain.\n+\n \n The '{caret}' (caret) notation\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n-- \n2.8.4.windows.1.3.ge328a54\n\n"},{"id":"291207","messageId":"20160711202518.532-9-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160711202518.532-1-philipoakley@iee.org","subject":"[PATCH v3 8/8] doc: revisions - clarify reachability examples","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-07-11T20:25:18Z","receivedAt":"2016-07-11T20:25:49Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"For the r1..r2 case, the exclusion of r1, rather than inclusion of r2,\nwould be the unexpected case in natural language for a simple linear\ndevelopment, i.e. start..end excludes start.\n\nSigned-off-by: Philip Oakley \n---\n Documentation/revisions.txt | 11 ++++++-----\n 1 file changed, 6 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex a3cd28b..dba4fc6 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -252,7 +252,8 @@ The '{caret}' (caret) notation\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n To exclude commits reachable from a commit, a prefix '{caret}'\n notation is used. E.g. '{caret}r1 r2' means commits reachable\n-from 'r2' but exclude the ones reachable from 'r1'.\n+from 'r2' but exclude those reachable from 'r1' (i.e. 'r1' and its\n+ancestors).\n \n The '..' (two-dot) range notation\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n@@ -290,12 +291,12 @@ Revision Range Summary\n ----------------------\n \n ''::\n-\tInclude commits that are reachable from (i.e. ancestors of)\n-\t.\n+\tInclude commits that are reachable from (i.e. and its\n+\tancestors).\n \n '{caret}'::\n-\tExclude commits that are reachable from (i.e. ancestors of)\n-\t.\n+\tExclude commits that are reachable from (i.e. and its\n+\tancestors).\n \n '..'::\n \tInclude commits that are reachable from but exclude\n-- \n2.8.4.windows.1.3.ge328a54\n\n"},{"id":"291208","messageId":"20160711202518.532-1-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160630202509.4472-1-philipoakley@iee.org","subject":"[PATCH v3 0/8] Name for A..B ranges?","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-07-11T20:25:10Z","receivedAt":"2016-07-11T20:25:52Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"This is the re-roll of the po/range-doc (2016-07-01) 3 commits and its\nfollow on patch.\n\nThe series has gained additional patches following the discussions\n($gmane/298790).\n\nThe original first 3 patches are unchanged, though 2/8 has been inserted\nto name the Left and Right ranges.\n\nThe extra four patches carefully tease out the clarification of\nreachability. Reachability is defined relative the ancestry chain thus\n(hopefully) avoiding misunderstandings.\n\nThe final patch updates the summary examples, and the tricky (for the\nuntutored reader) two dots case of a linear development where r1..r2\nexcludes r1 itself.\n\nThe patches can be squashed together if required.\n\nOriginal discussion starts at: $gmane/297908\nV1 patch series $gmane/298223\nV2 patch series $gmane/298689\n\n\nPhilip Oakley (8):\n doc: use 'symmetric difference' consistently\n doc: revisions - name the Left and Right sides\n doc: show the actual left, right, and boundary marks\n doc: give headings for the two and three dot notations\n doc: gitrevisions - use 'reachable' in page description\n doc: gitrevisions - clarify 'latter case' is revision walk\n doc: revisions - define `reachable`\n doc: revisions - clarify reachability examples\n\n Documentation/gitk.txt | 2 +-\n Documentation/gitrevisions.txt | 6 ++---\n Documentation/pretty-formats.txt | 2 +-\n Documentation/rev-list-options.txt | 4 +--\n Documentation/revisions.txt | 50 ++++++++++++++++++++++++++------------\n 5 files changed, 41 insertions(+), 23 deletions(-)\n\n-- \n2.8.4.windows.1.3.ge328a54\n\nfollows from msg-ID <20160630202509.4472-1-philipoakley@iee.org>\n"},{"id":"291209","messageId":"20160711202518.532-3-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160711202518.532-1-philipoakley@iee.org","subject":"[PATCH v3 2/8] doc: revisions - name the Left and Right sides","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-07-11T20:25:12Z","receivedAt":"2016-07-11T20:25:53Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"The terms Left and Right side originate from the symmetric\ndifference. Name them there.\n---\n Documentation/revisions.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 19314e3..79f6d03 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -256,7 +256,7 @@ A similar notation 'r1\\...r2' is called symmetric difference\n of 'r1' and 'r2' and is defined as\n 'r1 r2 --not $(git merge-base --all r1 r2)'.\n It is the set of commits that are reachable from either one of\n-'r1' or 'r2' but not from both.\n+'r1' (Left side) or 'r2' (Right side) but not from both.\n \n In these two shorthands, you can omit one end and let it default to HEAD.\n For example, 'origin..' is a shorthand for 'origin..HEAD' and asks \"What\n-- \n2.8.4.windows.1.3.ge328a54\n\n"},{"id":"291256","messageId":"5784F43E.3080400@xiplink.com","threadId":"42687","inReplyTo":"20160711202518.532-5-philipoakley@iee.org","subject":"Re: [PATCH v3 4/8] doc: give headings for the two and three dot notations","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2016-07-12T13:44:30Z","receivedAt":"2016-07-12T13:51:46Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"On 2016-07-11 04:25 PM, Philip Oakley wrote:\n> While there, also break out the other shorthand notations and\n> add a title for the revision range summary (which also appears\n> in git-rev-parse, so keep it mixed case).\n>\n> Signed-off-by: Philip Oakley \n> ---\n> Documentation/revisions.txt | 23 +++++++++++++++++------\n> 1 file changed, 17 insertions(+), 6 deletions(-)\n>\n> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\n> index 79f6d03..1c59e87 100644\n> --- a/Documentation/revisions.txt\n> +++ b/Documentation/revisions.txt\n> @@ -242,35 +242,46 @@ specifying a single revision with the notation described in the\n> previous section means the set of commits reachable from that\n> commit, following the commit ancestry chain.\n>\n> +The '{caret}' (caret) notation\n> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n> To exclude commits reachable from a commit, a prefix '{caret}'\n> notation is used. E.g. '{caret}r1 r2' means commits reachable\n> from 'r2' but exclude the ones reachable from 'r1'.\n\nAll of these headings render poorly in the manpage, at least for me \n(Ubuntu 16.04). Only the first word appears in bold; the '-quoted text \nis not bold but underlined, and the rest of the header is plain.\n\n\nAlso, I think calling this \"The ^ notation\" is confusing, because \nthere's already an earlier paragraph on the \"^\" syntax.\n\nMaybe we don't need a header here? I only suggest that because I'm \nhaving trouble coming up with a nice alternative. \"Commit Exclusion\"?\n\n>\n> -This set operation appears so often that there is a shorthand\n> +The '..' (two-dot) range notation\n> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nPerhaps \"Range notation\", to mirror the capitalization of \"Symmetric \nDifference\" in the next header?\n\n> +The '{caret}r1 r2' set operation appears so often that there is a shorthand\n> for it. When you have two commits 'r1' and 'r2' (named according\n> to the syntax explained in SPECIFYING REVISIONS above), you can ask\n> for commits that are reachable from r2 excluding those that are reachable\n> from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.\n>\n> +The '...' (three dot) Symmetric Difference notation\n> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n> A similar notation 'r1\\...r2' is called symmetric difference\n> of 'r1' and 'r2' and is defined as\n> 'r1 r2 --not $(git merge-base --all r1 r2)'.\n> It is the set of commits that are reachable from either one of\n> 'r1' (Left side) or 'r2' (Right side) but not from both.\n>\n> -In these two shorthands, you can omit one end and let it default to HEAD.\n> +In these two shorthand notations, you can omit one end and let it default to HEAD.\n> For example, 'origin..' is a shorthand for 'origin..HEAD' and asks \"What\n> did I do since I forked from the origin branch?\" Similarly, '..origin'\n> is a shorthand for 'HEAD..origin' and asks \"What did the origin do since\n> I forked from them?\" Note that '..' would mean 'HEAD..HEAD' which is an\n> empty range that is both reachable and unreachable from HEAD.\n\nUnfortunately the new headings make it appear that this paragraph is \nexclusively part of the '...' notation section. Folks reading the '..' \nsection are likely to skip it.\n\nI like the examples, though. I think it would be worthwhile to remove \nthis paragraph and fold it explicitly into the '..' and '...' notation \nsections.\n\nSo add something like this to the '..' section (only the first sentence \nhere is new):\n\n\tEither r1 or r2 can be omitted, in which case HEAD is used as\n\tthe default. For example, 'origin..' is a shorthand for\n\t'origin..HEAD' and asks \"What did I do since I forked from the\n\torigin branch?\" Similarly, '..origin' is a shorthand for\n\t'HEAD..origin' and asks \"What did the origin do since I forked\n\tfrom them?\" Note that '..' would mean 'HEAD..HEAD' which is an\n\tempty range that is both reachable and unreachable from HEAD.\n\nAnd also, add the same first sentence and a different example to the \n'...' section. Something like this:\n\n\tEither r1 or r2 can be omitted, in which case HEAD is used as\n\tthe default. For example, 'origin...' is a shorthand for\n\t'origin...HEAD' and asks \"What have I and origin both done\n\tsince I forked from the origin branch?\" Note that 'origin...'\n\tand '...origin' ask the same question.\n\n>\n> +Additional '{caret}' Shorthand notations\n> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n> Two other shorthands for naming a set that is formed by a commit\n> -and its parent commits exist. The 'r1{caret}@' notation means all\n> -parents of 'r1'. 'r1{caret}!' includes commit 'r1' but excludes\n> -all of its parents.\n> +and its parent commits exist.\n\nI think descriptions of ^@ and ^! should live under the main \ndescription of ^. That part already describes the numeric suffix, \nso describing a couple of special suffixes there seems like a natural fit.\n\nHowever, if you choose to keep this little section, you need to move the \nword \"exist\" earlier in the sentence:\n\n\tTwo other shorthands exist for naming a set that is formed\n\tby a commit and its parent commits.\n\n>\n> -To summarize:\n> +The 'r1{caret}@' notation means all parents of 'r1'.\n> +\n> +'r1{caret}!' includes commit 'r1' but excludes all of its parents.\n> +\n> +Revision Range Summary\n> +----------------------\n\nI think this should be a sub-heading (~~~~~~~), not a top-level heading.\n\n\t\tM.\n\n"},{"id":"291257","messageId":"5784F53E.9040104@xiplink.com","threadId":"42687","inReplyTo":"20160711202518.532-8-philipoakley@iee.org","subject":"Re: [PATCH v3 7/8] doc: revisions - define `reachable`","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2016-07-12T13:48:46Z","receivedAt":"2016-07-12T13:56:41Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"On 2016-07-11 04:25 PM, Philip Oakley wrote:\n> Do not self-define `reachable`, which can lead to misunderstanding.\n> Instead define `reachability` explictly.\n>\n> Signed-off-by: Philip Oakley \n> ---\n> Documentation/revisions.txt | 14 ++++++++++----\n> 1 file changed, 10 insertions(+), 4 deletions(-)\n>\n> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\n> index 1c59e87..a3cd28b 100644\n> --- a/Documentation/revisions.txt\n> +++ b/Documentation/revisions.txt\n> @@ -237,10 +237,16 @@ SPECIFYING RANGES\n> -----------------\n>\n> History traversing commands such as `git log` operate on a set\n> -of commits, not just a single commit. To these commands,\n> -specifying a single revision with the notation described in the\n> -previous section means the set of commits reachable from that\n> -commit, following the commit ancestry chain.\n> +of commits, not just a single commit.\n> +\n> +For these commands,\n> +specifying a single revision, using the notation described in the\n> +previous section, means the `reachable` set of commits of the given\n> +commit.\n\nBetter as \"... means the set of commits `reachable` from the given commit.\"\n\n> +\n> +A commit's reachable set is the commit itself and the commits of\n> +its ancestry chain.\n> +\n\ns/of/in/\n\n\t\tM.\n\n"},{"id":"291280","messageId":"xmqq1t2y7qi8.fsf@gitster.mtv.corp.google.com","threadId":"42687","inReplyTo":"20160711202518.532-3-philipoakley@iee.org","subject":"Re: [PATCH v3 2/8] doc: revisions - name the Left and Right sides","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-07-12T16:47:11Z","receivedAt":"2016-07-12T16:47:19Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley writes:\n\n> The terms Left and Right side originate from the symmetric\n> difference. Name them there.\n> ---\n\nSign-off?\n\n> Documentation/revisions.txt | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\n> index 19314e3..79f6d03 100644\n> --- a/Documentation/revisions.txt\n> +++ b/Documentation/revisions.txt\n> @@ -256,7 +256,7 @@ A similar notation 'r1\\...r2' is called symmetric difference\n> of 'r1' and 'r2' and is defined as\n> 'r1 r2 --not $(git merge-base --all r1 r2)'.\n> It is the set of commits that are reachable from either one of\n> -'r1' or 'r2' but not from both.\n> +'r1' (Left side) or 'r2' (Right side) but not from both.\n\nI think it is a good idea to call them explicitly left and right,\nbut I do not think they need to be capitalized here or on the title\nof the patch.\n\n> In these two shorthands, you can omit one end and let it default to HEAD.\n> For example, 'origin..' is a shorthand for 'origin..HEAD' and asks \"What\n"},{"id":"291283","messageId":"xmqqwpkq6b4d.fsf@gitster.mtv.corp.google.com","threadId":"42687","inReplyTo":"5784F43E.3080400@xiplink.com","subject":"Re: [PATCH v3 4/8] doc: give headings for the two and three dot notations","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-07-12T17:04:50Z","receivedAt":"2016-07-12T17:04:59Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Marc Branchaud writes:\n\n>> +The '{caret}' (caret) notation\n>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n>> To exclude commits reachable from a commit, a prefix '{caret}'\n>> notation is used. E.g. '{caret}r1 r2' means commits reachable\n>> from 'r2' but exclude the ones reachable from 'r1'.\n>\n> All of these headings render poorly in the manpage, at least for me\n> (Ubuntu 16.04). Only the first word appears in bold; the '-quoted\n> text is not bold but underlined, and the rest of the header is plain.\n>\n>\n> Also, I think calling this \"The ^ notation\" is confusing, because\n> there's already an earlier paragraph on the \"^\" syntax.\n>\n> Maybe we don't need a header here? I only suggest that because I'm\n> having trouble coming up with a nice alternative. \"Commit Exclusion\"?\n\nThanks for pointing out the potential confusion between ^X (exclude\nreachable), and X^ (the first parent). Commit exclusion is probably\na good heading.\n\n>> -This set operation appears so often that there is a shorthand\n>> +The '..' (two-dot) range notation\n>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n>\n> Perhaps \"Range notation\", to mirror the capitalization of \"Symmetric\n> Difference\" in the next header?\n>> ...\n>> +The '...' (three dot) Symmetric Difference notation\n\nThis uses a strange capitalization rule. s/notation/Notation/\nperhaps? The same comment for \"Additional Shothand notation\" below.\n\n>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n>> A similar notation 'r1\\...r2' is called symmetric difference\n>> of 'r1' and 'r2' and is defined as\n>> 'r1 r2 --not $(git merge-base --all r1 r2)'.\n>> It is the set of commits that are reachable from either one of\n>> 'r1' (Left side) or 'r2' (Right side) but not from both.\n>>\n>> -In these two shorthands, you can omit one end and let it default to HEAD.\n>> +In these two shorthand notations, you can omit one end and let it default to HEAD.\n>> For example, 'origin..' is a shorthand for 'origin..HEAD' and asks \"What\n>> did I do since I forked from the origin branch?\" Similarly, '..origin'\n>> is a shorthand for 'HEAD..origin' and asks \"What did the origin do since\n>> I forked from them?\" Note that '..' would mean 'HEAD..HEAD' which is an\n>> empty range that is both reachable and unreachable from HEAD.\n>\n> Unfortunately the new headings make it appear that this paragraph is\n> exclusively part of the '...' notation section. Folks reading the\n> ..' section are likely to skip it.\n>\n> I like the examples, though. I think it would be worthwhile to remove\n> this paragraph and fold it explicitly into the '..' and '...' notation\n> sections.\n\nAn alternative would be to have\n\n - Dotted range notations\n - Two-dot notation\n - Three-dot notation\n\nwhich would help make it stand out that defaulting is common\ncharacteristics between .. and ... notations. But I can imagine\nthat your \"with slight duplication\" variant below would work well,\ntoo.\n\n> So add something like this to the '..' section (only the first\n> sentence here is new):\n>\n> \tEither r1 or r2 can be omitted, in which case HEAD is used as\n> \tthe default. For example, 'origin..' is a shorthand for\n> \t'origin..HEAD' and asks \"What did I do since I forked from the\n> \torigin branch?\" Similarly, '..origin' is a shorthand for\n> \t'HEAD..origin' and asks \"What did the origin do since I forked\n> \tfrom them?\" Note that '..' would mean 'HEAD..HEAD' which is an\n> \tempty range that is both reachable and unreachable from HEAD.\n>\n> And also, add the same first sentence and a different example to the\n> ...' section. Something like this:\n>\n> \tEither r1 or r2 can be omitted, in which case HEAD is used as\n> \tthe default. For example, 'origin...' is a shorthand for\n> \t'origin...HEAD' and asks \"What have I and origin both done\n> \tsince I forked from the origin branch?\" Note that 'origin...'\n> \tand '...origin' ask the same question.\n\n>> +Additional '{caret}' Shorthand notations\n>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n>> Two other shorthands for naming a set that is formed by a commit\n>> -and its parent commits exist. The 'r1{caret}@' notation means all\n>> -parents of 'r1'. 'r1{caret}!' includes commit 'r1' but excludes\n>> -all of its parents.\n>> +and its parent commits exist.\n>\n> I think descriptions of ^@ and ^! should live under the main\n> description of ^. That part already describes the numeric\n> suffix, so describing a couple of special suffixes there seems like a\n> natural fit.\n\nI actually think this is a good place to have them described.\n^ is about specifying a single commit. These two are\nnot that (you can say HEAD^2^@ but you cannot say HEAD^@^2, for\nexample).\n\n"},{"id":"291298","messageId":"xmqqinwa4puf.fsf@gitster.mtv.corp.google.com","threadId":"42687","inReplyTo":"20160711202518.532-1-philipoakley@iee.org","subject":"Re: [PATCH v3 0/8] Name for A..B ranges?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-07-12T19:29:44Z","receivedAt":"2016-07-12T19:29:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley writes:\n\n> This is the re-roll of the po/range-doc (2016-07-01) 3 commits and its\n> follow on patch.\n>\n> The series has gained additional patches following the discussions\n> ($gmane/298790).\n>\n> The original first 3 patches are unchanged, though 2/8 has been inserted\n> to name the Left and Right ranges.\n>\n> The extra four patches carefully tease out the clarification of\n> reachability. Reachability is defined relative the ancestry chain thus\n> (hopefully) avoiding misunderstandings.\n>\n> The final patch updates the summary examples, and the tricky (for the\n> untutored reader) two dots case of a linear development where r1..r2\n> excludes r1 itself.\n>\n> The patches can be squashed together if required.\n\nLooked mostly sensible, except for a few things mentioned in the\nreviews by Marc (to which I mostly agree with).\n\nThanks.\n\n"},{"id":"291306","messageId":"37D91D4F45C6444792E9B9205EF88BE1@PhilipOakley","threadId":"42687","inReplyTo":"5784F43E.3080400@xiplink.com","subject":"Re: [PATCH v3 4/8] doc: give headings for the two and three dot notations","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-07-12T21:41:35Z","receivedAt":"2016-07-12T21:42:05Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Marc Branchaud\" \n> On 2016-07-11 04:25 PM, Philip Oakley wrote:\n>> While there, also break out the other shorthand notations and\n>> add a title for the revision range summary (which also appears\n>> in git-rev-parse, so keep it mixed case).\n>>\n>> Signed-off-by: Philip Oakley \n>> ---\n>> Documentation/revisions.txt | 23 +++++++++++++++++------\n>> 1 file changed, 17 insertions(+), 6 deletions(-)\n>>\n>> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\n>> index 79f6d03..1c59e87 100644\n>> --- a/Documentation/revisions.txt\n>> +++ b/Documentation/revisions.txt\n>> @@ -242,35 +242,46 @@ specifying a single revision with the notation \n>> described in the\n>> previous section means the set of commits reachable from that\n>> commit, following the commit ancestry chain.\n>>\n>> +The '{caret}' (caret) notation\n>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n>> To exclude commits reachable from a commit, a prefix '{caret}'\n>> notation is used. E.g. '{caret}r1 r2' means commits reachable\n>> from 'r2' but exclude the ones reachable from 'r1'.\n>\n> All of these headings render poorly in the manpage, at least for me \n> (Ubuntu 16.04). Only the first word appears in bold; the '-quoted text is \n> not bold but underlined, and the rest of the header is plain.\n\nWhich doc package is that with? It had formatted OK for the html web pages.\n\n>\n>\n> Also, I think calling this \"The ^ notation\" is confusing, because there's \n> already an earlier paragraph on the \"^\" syntax.\n\nYes, I noticed that after sending. Maybe \"^\" (i.e. include the \npart) to show that its a prefix not a suffix\n\n>\n> Maybe we don't need a header here? I only suggest that because I'm having \n> trouble coming up with a nice alternative. \"Commit Exclusion\"?\n>\n\nPart of the earlier discussions as about avoiding new termininologies just \nfor the sake of it.\n\n>>\n>> -This set operation appears so often that there is a shorthand\n>> +The '..' (two-dot) range notation\n>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n>\n> Perhaps \"Range notation\", to mirror the capitalization of \"Symmetric \n> Difference\" in the next header?\n\n\nOK\n>\n>> +The '{caret}r1 r2' set operation appears so often that there is a \n>> shorthand\n>> for it. When you have two commits 'r1' and 'r2' (named according\n>> to the syntax explained in SPECIFYING REVISIONS above), you can ask\n>> for commits that are reachable from r2 excluding those that are \n>> reachable\n>> from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.\n>>\n>> +The '...' (three dot) Symmetric Difference notation\n>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n>> A similar notation 'r1\\...r2' is called symmetric difference\n>> of 'r1' and 'r2' and is defined as\n>> 'r1 r2 --not $(git merge-base --all r1 r2)'.\n>> It is the set of commits that are reachable from either one of\n>> 'r1' (Left side) or 'r2' (Right side) but not from both.\n>>\n>> -In these two shorthands, you can omit one end and let it default to \n>> HEAD.\n>> +In these two shorthand notations, you can omit one end and let it \n>> default to HEAD.\n>> For example, 'origin..' is a shorthand for 'origin..HEAD' and asks \n>> \"What\n>> did I do since I forked from the origin branch?\" Similarly, '..origin'\n>> is a shorthand for 'HEAD..origin' and asks \"What did the origin do \n>> since\n>> I forked from them?\" Note that '..' would mean 'HEAD..HEAD' which is \n>> an\n>> empty range that is both reachable and unreachable from HEAD.\n>\n> Unfortunately the new headings make it appear that this paragraph is \n> exclusively part of the '...' notation section. Folks reading the '..' \n> section are likely to skip it.\n\nOK\n\n>\n> I like the examples, though. I think it would be worthwhile to remove \n> this paragraph and fold it explicitly into the '..' and '...' notation \n> sections.\n>\n> So add something like this to the '..' section (only the first sentence \n> here is new):\n>\n> Either r1 or r2 can be omitted, in which case HEAD is used as\n> the default. For example, 'origin..' is a shorthand for\n> 'origin..HEAD' and asks \"What did I do since I forked from the\n> origin branch?\" Similarly, '..origin' is a shorthand for\n> 'HEAD..origin' and asks \"What did the origin do since I forked\n> from them?\" Note that '..' would mean 'HEAD..HEAD' which is an\n> empty range that is both reachable and unreachable from HEAD.\n>\n> And also, add the same first sentence and a different example to the '...' \n> section. Something like this:\n>\n> Either r1 or r2 can be omitted, in which case HEAD is used as\n> the default. For example, 'origin...' is a shorthand for\n> 'origin...HEAD' and asks \"What have I and origin both done\n> since I forked from the origin branch?\" Note that 'origin...'\n> and '...origin' ask the same question.\n>\n>>\n>> +Additional '{caret}' Shorthand notations\n>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n>> Two other shorthands for naming a set that is formed by a commit\n>> -and its parent commits exist. The 'r1{caret}@' notation means all\n>> -parents of 'r1'. 'r1{caret}!' includes commit 'r1' but excludes\n>> -all of its parents.\n>> +and its parent commits exist.\n>\n> I think descriptions of ^@ and ^! should live under the main \n> description of ^. That part already describes the numeric suffix, so \n> describing a couple of special suffixes there seems like a natural fit.\n\nIsn't it that these are ranges of commits, rather than a single commit, so \nwould go in this part of the docs, but I see your point.\n\n>\n> However, if you choose to keep this little section, you need to move the \n> word \"exist\" earlier in the sentence:\n\nOK.\n>\n> Two other shorthands exist for naming a set that is formed\n> by a commit and its parent commits.\n>\n>>\n>> -To summarize:\n>> +The 'r1{caret}@' notation means all parents of 'r1'.\n>> +\n>> +'r1{caret}!' includes commit 'r1' but excludes all of its parents.\n>> +\n>> +Revision Range Summary\n>> +----------------------\n>\n> I think this should be a sub-heading (~~~~~~~), not a top-level heading.\n>\n\nIn the contect of the other pages it's included in, the use of lower case, \nis the next down level. ALL CAPS would be the top level heading.\n\nI'll review.\n--\nPhilip \n\n"},{"id":"291307","messageId":"27A6AC8B1E3B4C80B95AFF19CEF7A962@PhilipOakley","threadId":"42687","inReplyTo":"5784F53E.9040104@xiplink.com","subject":"Re: [PATCH v3 7/8] doc: revisions - define `reachable`","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-07-12T21:44:29Z","receivedAt":"2016-07-12T21:46:18Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Marc Branchaud\" \n> On 2016-07-11 04:25 PM, Philip Oakley wrote:\n>> Do not self-define `reachable`, which can lead to misunderstanding.\n>> Instead define `reachability` explictly.\n>>\n>> Signed-off-by: Philip Oakley \n>> ---\n>> Documentation/revisions.txt | 14 ++++++++++----\n>> 1 file changed, 10 insertions(+), 4 deletions(-)\n>>\n>> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\n>> index 1c59e87..a3cd28b 100644\n>> --- a/Documentation/revisions.txt\n>> +++ b/Documentation/revisions.txt\n>> @@ -237,10 +237,16 @@ SPECIFYING RANGES\n>> -----------------\n>>\n>> History traversing commands such as `git log` operate on a set\n>> -of commits, not just a single commit. To these commands,\n>> -specifying a single revision with the notation described in the\n>> -previous section means the set of commits reachable from that\n>> -commit, following the commit ancestry chain.\n>> +of commits, not just a single commit.\n>> +\n>> +For these commands,\n>> +specifying a single revision, using the notation described in the\n>> +previous section, means the `reachable` set of commits of the given\n>> +commit.\n>\n> Better as \"... means the set of commits `reachable` from the given \n> commit.\"\n\nOK. The main aspect is show that 'reachable' is a specific term.\n\n>\n>> +\n>> +A commit's reachable set is the commit itself and the commits of\n>> +its ancestry chain.\n>> +\n>\n> s/of/in/\n\nOK.\n>\n--\nPhilip \n\n"},{"id":"291308","messageId":"5ECE61F3B9CE4C6F80718AE457AF8278@PhilipOakley","threadId":"42687","inReplyTo":"xmqq1t2y7qi8.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH v3 2/8] doc: revisions - name the Left and Right sides","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-07-12T21:47:15Z","receivedAt":"2016-07-12T21:48:51Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \n> Philip Oakley writes:\n>\n>> The terms Left and Right side originate from the symmetric\n>> difference. Name them there.\n>> ---\n>\n> Sign-off?\n\nOops - will fix.\n>\n>> Documentation/revisions.txt | 2 +-\n>> 1 file changed, 1 insertion(+), 1 deletion(-)\n>>\n>> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\n>> index 19314e3..79f6d03 100644\n>> --- a/Documentation/revisions.txt\n>> +++ b/Documentation/revisions.txt\n>> @@ -256,7 +256,7 @@ A similar notation 'r1\\...r2' is called symmetric \n>> difference\n>> of 'r1' and 'r2' and is defined as\n>> 'r1 r2 --not $(git merge-base --all r1 r2)'.\n>> It is the set of commits that are reachable from either one of\n>> -'r1' or 'r2' but not from both.\n>> +'r1' (Left side) or 'r2' (Right side) but not from both.\n>\n> I think it is a good idea to call them explicitly left and right,\n> but I do not think they need to be capitalized here or on the title\n> of the patch.\n\nOK - can fix.\n\n>\n>> In these two shorthands, you can omit one end and let it default to \n>> HEAD.\n>> For example, 'origin..' is a shorthand for 'origin..HEAD' and asks \"What\n>\n--\nPhilip \n\n"},{"id":"291309","messageId":"D94C739D5C334AFE9E5E8410147899EA@PhilipOakley","threadId":"42687","inReplyTo":"xmqqwpkq6b4d.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH v3 4/8] doc: give headings for the two and three dot notations","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-07-12T22:11:42Z","receivedAt":"2016-07-12T22:12:03Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \n> Marc Branchaud writes:\n>\n>>> +The '{caret}' (caret) notation\n>>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n>>> To exclude commits reachable from a commit, a prefix '{caret}'\n>>> notation is used. E.g. '{caret}r1 r2' means commits reachable\n>>> from 'r2' but exclude the ones reachable from 'r1'.\n>>\n>> All of these headings render poorly in the manpage, at least for me\n>> (Ubuntu 16.04). Only the first word appears in bold; the '-quoted\n>> text is not bold but underlined, and the rest of the header is plain.\n>>\n>>\n>> Also, I think calling this \"The ^ notation\" is confusing, because\n>> there's already an earlier paragraph on the \"^\" syntax.\n>>\n>> Maybe we don't need a header here? I only suggest that because I'm\n>> having trouble coming up with a nice alternative. \"Commit Exclusion\"?\n>\n> Thanks for pointing out the potential confusion between ^X (exclude\n> reachable), and X^ (the first parent). Commit exclusion is probably\n> a good heading.\n>\nOK - I'll see about incorporating that.\n\n>>> -This set operation appears so often that there is a shorthand\n>>> +The '..' (two-dot) range notation\n>>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n>>\n>> Perhaps \"Range notation\", to mirror the capitalization of \"Symmetric\n>> Difference\" in the next header?\n>>> ...\n>>> +The '...' (three dot) Symmetric Difference notation\n>\n> This uses a strange capitalization rule. s/notation/Notation/\n> perhaps? The same comment for \"Additional Shothand notation\" below.\n>\n\nI'd just capitalised the specific term. Will change.\n\n>>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n>>> A similar notation 'r1\\...r2' is called symmetric difference\n>>> of 'r1' and 'r2' and is defined as\n>>> 'r1 r2 --not $(git merge-base --all r1 r2)'.\n>>> It is the set of commits that are reachable from either one of\n>>> 'r1' (Left side) or 'r2' (Right side) but not from both.\n>>>\n>>> -In these two shorthands, you can omit one end and let it default to \n>>> HEAD.\n>>> +In these two shorthand notations, you can omit one end and let it \n>>> default to HEAD.\n>>> For example, 'origin..' is a shorthand for 'origin..HEAD' and asks \n>>> \"What\n>>> did I do since I forked from the origin branch?\" Similarly, \n>>> '..origin'\n>>> is a shorthand for 'HEAD..origin' and asks \"What did the origin do \n>>> since\n>>> I forked from them?\" Note that '..' would mean 'HEAD..HEAD' which is \n>>> an\n>>> empty range that is both reachable and unreachable from HEAD.\n>>\n>> Unfortunately the new headings make it appear that this paragraph is\n>> exclusively part of the '...' notation section. Folks reading the\n>> ..' section are likely to skip it.\n>>\n>> I like the examples, though. I think it would be worthwhile to remove\n>> this paragraph and fold it explicitly into the '..' and '...' notation\n>> sections.\n>\n> An alternative would be to have\n>\n> - Dotted range notations\n> - Two-dot notation\n> - Three-dot notation\n>\n> which would help make it stand out that defaulting is common\n> characteristics between .. and ... notations. But I can imagine\n> that your \"with slight duplication\" variant below would work well,\n> too.\n\nI'll look into that.\n\n>\n>> So add something like this to the '..' section (only the first\n>> sentence here is new):\n>>\n>> Either r1 or r2 can be omitted, in which case HEAD is used as\n>> the default. For example, 'origin..' is a shorthand for\n>> 'origin..HEAD' and asks \"What did I do since I forked from the\n>> origin branch?\" Similarly, '..origin' is a shorthand for\n>> 'HEAD..origin' and asks \"What did the origin do since I forked\n>> from them?\" Note that '..' would mean 'HEAD..HEAD' which is an\n>> empty range that is both reachable and unreachable from HEAD.\n>>\n>> And also, add the same first sentence and a different example to the\n>> ...' section. Something like this:\n>>\n>> Either r1 or r2 can be omitted, in which case HEAD is used as\n>> the default. For example, 'origin...' is a shorthand for\n>> 'origin...HEAD' and asks \"What have I and origin both done\n>> since I forked from the origin branch?\" Note that 'origin...'\n>> and '...origin' ask the same question.\n>\n>>> +Additional '{caret}' Shorthand notations\n>>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n>>> Two other shorthands for naming a set that is formed by a commit\n>>> -and its parent commits exist. The 'r1{caret}@' notation means all\n>>> -parents of 'r1'. 'r1{caret}!' includes commit 'r1' but excludes\n>>> -all of its parents.\n>>> +and its parent commits exist.\n>>\n>> I think descriptions of ^@ and ^! should live under the main\n>> description of ^. That part already describes the numeric\n>> suffix, so describing a couple of special suffixes there seems like a\n>> natural fit.\n>\n> I actually think this is a good place to have them described.\n> ^ is about specifying a single commit. These two are\n> not that (you can say HEAD^2^@ but you cannot say HEAD^@^2, for\n> example).\n\nThese two are special cases I'm not too familiar with, particularly the r1^! \nwhich I didn't undesrtand from the description...\n\n--\nPhilip \n\n"},{"id":"291310","messageId":"20160712221205.GA9390@sigill.intra.peff.net","threadId":"42687","inReplyTo":"37D91D4F45C6444792E9B9205EF88BE1@PhilipOakley","subject":"Re: [PATCH v3 4/8] doc: give headings for the two and three dot notations","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2016-07-12T22:12:06Z","receivedAt":"2016-07-12T22:12:26Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Jul 12, 2016 at 10:41:35PM +0100, Philip Oakley wrote:\n\n> > > +The '{caret}' (caret) notation\n> > > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n> > > To exclude commits reachable from a commit, a prefix '{caret}'\n> > > notation is used. E.g. '{caret}r1 r2' means commits reachable\n> > > from 'r2' but exclude the ones reachable from 'r1'.\n> > \n> > All of these headings render poorly in the manpage, at least for me\n> > (Ubuntu 16.04). Only the first word appears in bold; the '-quoted text\n> > is not bold but underlined, and the rest of the header is plain.\n> \n> Which doc package is that with? It had formatted OK for the html web pages.\n\nI get the same with:\n\n make gitrevisions.7\n man -l gitrevisions.7\n\nAsciidoc 8.6.9, docbook-xsl 4.5 if it matters.\n\nRendering single-quotes as underline is normal in this case (though it's\nnot great for punctuation like this, as it kind of blends with the dots;\nI know we use it elsewhere in this document, though). The failure to\ncontinue the bold through the end of line looks like a bug, though.\n\nThe generated XML (from asciidoc) looks reasonable:\n\n The <emphasis>..</emphasis> (two-dot) range notation\n\nThe roff looks like:\n\n .SS \"The \\fI\\&.\\&.\\fR (two\\-dot) range notation\"\n\nThe \"\\fR\" switches us back to \"Roman\" from italics, which is presumably\nthe problem. We really want to say \"switch back what we were using\nbefore \\fI\".\n\nSwitching it to \"\\fP\" fixes it, but it's not clear to me if that's\nactually portable, or a groff-ism. I don't know roff very well and\ndocumentation seems to be quite hard to find. So it's either a bug in\ndocbook, or an intentional decision they've made because roff can't\nportably do better. I'm not sure which.\n\n-Peff\n"},{"id":"291312","messageId":"7486C42170C44043AB17BA9A47A6C8C2@PhilipOakley","threadId":"42687","inReplyTo":"xmqqinwa4puf.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH v3 0/8] Name for A..B ranges?","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-07-12T22:29:05Z","receivedAt":"2016-07-12T22:30:06Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \n> Philip Oakley writes:\n> \n>> This is the re-roll of the po/range-doc (2016-07-01) 3 commits and its\n>> follow on patch.\n>>\n>> The series has gained additional patches following the discussions\n>> ($gmane/298790).\n..\n>>\n>> The patches can be squashed together if required.\n> \n> Looked mostly sensible, except for a few things mentioned in the\n> reviews by Marc (to which I mostly agree with).\n> \n\nThanks. I'll update in the next few days.\n\nPhilip\n"},{"id":"291725","messageId":"578E4F4A.2020708@gmail.com","threadId":"42687","inReplyTo":"D94C739D5C334AFE9E5E8410147899EA@PhilipOakley","subject":"Re: [PATCH v3 4/8] doc: give headings for the two and three dot notations","fromName":"Jakub Narębski","fromEmail":"jnareb@gmail.com","sentAt":"2016-07-19T16:03:22Z","receivedAt":"2016-07-19T16:03:34Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"W dniu 2016-07-13 o 00:11, Philip Oakley pisze:\n> From: \"Junio C Hamano\" \n[...]\n>> I actually think this is a good place to have them described.\n>> ^ is about specifying a single commit. These two are\n>> not that (you can say HEAD^2^@ but you cannot say HEAD^@^2, for\n>> example).\n> \n> These two are special cases I'm not too familiar with, particularly\n> the r1^! which I didn't understand from the description...\n\n^@ is all parents of , that is\n\n ^@ == ^1 ^2 ... ^\n\nwhere is number of parents commit has.\n\n\n^! is (if standalone) a single commit range, only revision.\nIt is actually\n\n ^! == ( --not ^@ )\n\nthat is, reachable from but not from any of its parents.\nParentheses here denote that `--not` does not affect the rest of\nrev-like parameters.\n\n\nHope that helps\n-- \nJakub Narębski\n"},{"id":"291756","messageId":"1D7B90EDE07E4B1BA1175C18946D5D2D@PhilipOakley","threadId":"42687","inReplyTo":"578E4F4A.2020708@gmail.com","subject":"Re: [PATCH v3 4/8] doc: give headings for the two and three dot notations","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-07-19T19:15:25Z","receivedAt":"2016-07-19T19:15:33Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Jakub Narębski\" \n>W dniu 2016-07-13 o 00:11, Philip Oakley pisze:\n>> From: \"Junio C Hamano\" \n> [...]\n>>> I actually think this is a good place to have them described.\n>>> ^ is about specifying a single commit. These two are\n>>> not that (you can say HEAD^2^@ but you cannot say HEAD^@^2, for\n>>> example).\n>>\n>> These two are special cases I'm not too familiar with, particularly\n>> the r1^! which I didn't understand from the description...\n>\n> ^@ is all parents of , that is\n>\n> ^@ == ^1 ^2 ... ^\n>\n> where is number of parents commit has.\n>\n>\n> ^! is (if standalone) a single commit range, only revision.\n> It is actually\n>\n> ^! == ( --not ^@ )\n>\n> that is, reachable from but not from any of its parents.\n> Parentheses here denote that `--not` does not affect the rest of\n> rev-like parameters.\n>\n>\n> Hope that helps\n> -- \n\nThe tricky part is seeing that, rather than being a depth wise range, it's \nactually a width wise range that is designed to cover the scenarios around \nmerges\n\ne.g. $ git rev-parse 6c71a849^!\nor $ git rev-parse 6c71a849^@\n\nIn the doc that I'm updating I'll add a comment that it's particulalry \nuseful around merges.\n\nMind you I did see dscho quote it in $gmane/299738\n\" You can also inspect the diff of a commit, using the ^! suffix, e.g.\n\n git difftool -x diff origin/master~3^!\n\n--\nPhilip \n\n"},{"id":"291863","messageId":"20160720211007.5520-3-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160720211007.5520-1-philipoakley@iee.org","subject":"[PATCH v4 2/8] doc: revisions - name the left and right sides","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-07-20T21:10:01Z","receivedAt":"2016-07-20T21:10:30Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"The terms left and right side originate from the symmetric\ndifference. Name them there.\n\nSigned-off-by: Philip Oakley \n---\n Documentation/revisions.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 19314e3..6e9cd41 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -256,7 +256,7 @@ A similar notation 'r1\\...r2' is called symmetric difference\n of 'r1' and 'r2' and is defined as\n 'r1 r2 --not $(git merge-base --all r1 r2)'.\n It is the set of commits that are reachable from either one of\n-'r1' or 'r2' but not from both.\n+'r1' (left side) or 'r2' (right side) but not from both.\n \n In these two shorthands, you can omit one end and let it default to HEAD.\n For example, 'origin..' is a shorthand for 'origin..HEAD' and asks \"What\n-- \n2.9.0.windows.1\n\n"},{"id":"291864","messageId":"20160720211007.5520-1-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160711202518.532-1-philipoakley@iee.org","subject":"[PATCH v4 0/8] Name for A..B ranges?","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-07-20T21:09:59Z","receivedAt":"2016-07-20T21:10:34Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"This is the V4 re-roll of the po/range-doc (2016-07-01) 3 commits and its\nfollow on patch.\n\nCapitalisation has been fixed.\nHeading levels for man pages has been fixed.\nQuoting of the caret has been fixed.\nThe extra width wise 'caret' shorthands now mention their applicability to merge commits.\n\nNo change in the number of patches. Interdiff below.\n\nThe patches carefully tease out the clarification of\nreachability. Reachability is defined relative the ancestry chain thus\n(hopefully) avoiding misunderstandings.\n\nThe final patch updates the summary examples, and the tricky (for the\nuntutored reader) two dots case of a linear development where r1..r2\nexcludes r1 itself.\n\nThe patches can be squashed together if required.\n\nOriginal discussion starts at: $gmane/297908\nV1 patch series $gmane/298223\nV2 patch series $gmane/298689\nV3 patch series $gmane/299293\n\n\nPhilip Oakley (8):\n doc: use 'symmetric difference' consistently\n doc: revisions - name the left and right sides\n doc: show the actual left, right, and boundary marks\n doc: give headings for the two and three dot notations\n doc: gitrevisions - use 'reachable' in page description\n doc: gitrevisions - clarify 'latter case' is revision walk\n doc: revisions - define `reachable`\n doc: revisions - clarify reachability examples\n\n Documentation/gitk.txt | 2 +-\n Documentation/gitrevisions.txt | 6 +--\n Documentation/pretty-formats.txt | 2 +-\n Documentation/rev-list-options.txt | 4 +-\n Documentation/revisions.txt | 83 ++++++++++++++++++++++++--------------\n 5 files changed, 59 insertions(+), 38 deletions(-)\n\n interdiff:\n \n diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex dba4fc6..14622cc 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -241,35 +241,38 @@ of commits, not just a single commit.\n \n For these commands,\n specifying a single revision, using the notation described in the\n-previous section, means the `reachable` set of commits of the given\n+previous section, means the set of commits `reachable` from the given\n commit.\n \n-A commit's reachable set is the commit itself and the commits of\n+A commit's reachable set is the commit itself and the commits in\n its ancestry chain.\n \n \n-The '{caret}' (caret) notation\n-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n-To exclude commits reachable from a commit, a prefix '{caret}'\n-notation is used. E.g. '{caret}r1 r2' means commits reachable\n-from 'r2' but exclude those reachable from 'r1' (i.e. 'r1' and its\n-ancestors).\n-\n-The '..' (two-dot) range notation\n-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n-The '{caret}r1 r2' set operation appears so often that there is a shorthand\n-for it. When you have two commits 'r1' and 'r2' (named according\n-to the syntax explained in SPECIFYING REVISIONS above), you can ask\n-for commits that are reachable from r2 excluding those that are reachable\n-from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.\n-\n-The '...' (three dot) Symmetric Difference notation\n-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n-A similar notation 'r1\\...r2' is called symmetric difference\n-of 'r1' and 'r2' and is defined as\n-'r1 r2 --not $(git merge-base --all r1 r2)'.\n-It is the set of commits that are reachable from either one of\n-'r1' (Left side) or 'r2' (Right side) but not from both.\n+Commit Exclusions\n+~~~~~~~~~~~~~~~~~\n+\n+'{caret}' (caret) Notation::\n+ To exclude commits reachable from a commit, a prefix '{caret}'\n+ notation is used. E.g. '{caret}r1 r2' means commits reachable\n+ from 'r2' but exclude the ones reachable from 'r1' (i.e. 'r1' and\n+ its ancestors).\n+\n+Dotted Range Notations\n+~~~~~~~~~~~~~~~~~~~~~~\n+\n+The '..' (two-dot) Range Notation::\n+ The '{caret}r1 r2' set operation appears so often that there is a shorthand\n+ for it. When you have two commits 'r1' and 'r2' (named according\n+ to the syntax explained in SPECIFYING REVISIONS above), you can ask\n+ for commits that are reachable from r2 excluding those that are reachable\n+ from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.\n+\n+The '...' (three dot) Symmetric Difference Notation::\n+ A similar notation 'r1\\...r2' is called symmetric difference\n+ of 'r1' and 'r2' and is defined as\n+ 'r1 r2 --not $(git merge-base --all r1 r2)'.\n+ It is the set of commits that are reachable from either one of\n+ 'r1' (left side) or 'r2' (right side) but not from both.\n \n In these two shorthand notations, you can omit one end and let it default to HEAD.\n For example, 'origin..' is a shorthand for 'origin..HEAD' and asks \"What\n@@ -278,10 +281,10 @@ is a shorthand for 'HEAD..origin' and asks \"What did the origin do since\n I forked from them?\" Note that '..' would mean 'HEAD..HEAD' which is an\n empty range that is both reachable and unreachable from HEAD.\n \n-Additional '{caret}' Shorthand notations\n-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n-Two other shorthands for naming a set that is formed by a commit\n-and its parent commits exist.\n+Special '{caret}' Shorthand Notations\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+Two other shorthands exist, particularly useful for merge commits, is\n+for naming a set that is formed by a commit and its parent commits.\n \n The 'r1{caret}@' notation means all parents of 'r1'.\n \n\n-- \n2.9.0.windows.1\n\n"},{"id":"291865","messageId":"20160720211007.5520-8-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160720211007.5520-1-philipoakley@iee.org","subject":"[PATCH v4 7/8] doc: revisions - define `reachable`","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-07-20T21:10:06Z","receivedAt":"2016-07-20T21:10:35Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Do not self-define `reachable`, which can lead to misunderstanding.\nInstead define `reachability` explictly.\n\nSigned-off-by: Philip Oakley \n---\n Documentation/revisions.txt | 14 ++++++++++----\n 1 file changed, 10 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 5b37283..d3b7cee 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -237,10 +237,16 @@ SPECIFYING RANGES\n -----------------\n \n History traversing commands such as `git log` operate on a set\n-of commits, not just a single commit. To these commands,\n-specifying a single revision with the notation described in the\n-previous section means the set of commits reachable from that\n-commit, following the commit ancestry chain.\n+of commits, not just a single commit.\n+\n+For these commands,\n+specifying a single revision, using the notation described in the\n+previous section, means the set of commits `reachable` from the given\n+commit.\n+\n+A commit's reachable set is the commit itself and the commits in\n+its ancestry chain.\n+\n \n Commit Exclusions\n ~~~~~~~~~~~~~~~~~\n-- \n2.9.0.windows.1\n\n"},{"id":"291866","messageId":"20160720211007.5520-9-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160720211007.5520-1-philipoakley@iee.org","subject":"[PATCH v4 8/8] doc: revisions - clarify reachability examples","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-07-20T21:10:07Z","receivedAt":"2016-07-20T21:10:36Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":" For the r1..r2 case, the exclusion of r1, rather than inclusion of r2,\n would be the unexpected case in natural language for a simple linear\n development, i.e. start..end excludes start.\n\nSigned-off-by: Philip Oakley \n---\n Documentation/revisions.txt | 11 ++++++-----\n 1 file changed, 6 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex d3b7cee..14622cc 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -254,7 +254,8 @@ Commit Exclusions\n '{caret}' (caret) Notation::\n To exclude commits reachable from a commit, a prefix '{caret}'\n notation is used. E.g. '{caret}r1 r2' means commits reachable\n- from 'r2' but exclude the ones reachable from 'r1'.\n+ from 'r2' but exclude the ones reachable from 'r1' (i.e. 'r1' and\n+ its ancestors).\n \n Dotted Range Notations\n ~~~~~~~~~~~~~~~~~~~~~~\n@@ -293,12 +294,12 @@ Revision Range Summary\n ----------------------\n \n ''::\n-\tInclude commits that are reachable from (i.e. ancestors of)\n-\t.\n+\tInclude commits that are reachable from (i.e. and its\n+\tancestors).\n \n '{caret}'::\n-\tExclude commits that are reachable from (i.e. ancestors of)\n-\t.\n+\tExclude commits that are reachable from (i.e. and its\n+\tancestors).\n \n '..'::\n \tInclude commits that are reachable from but exclude\n-- \n2.9.0.windows.1\n\n"},{"id":"291867","messageId":"20160720211007.5520-7-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160720211007.5520-1-philipoakley@iee.org","subject":"[PATCH v4 6/8] doc: gitrevisions - clarify 'latter case' is revision walk","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-07-20T21:10:05Z","receivedAt":"2016-07-20T21:10:37Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"The prior sentence has too many clauses for easy parsing.\nReplace 'the latter case' with a direct quote.\n\nSigned-off-by: Philip Oakley \n---\n Documentation/gitrevisions.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/gitrevisions.txt b/Documentation/gitrevisions.txt\nindex 33039c6..27dec5b 100644\n--- a/Documentation/gitrevisions.txt\n+++ b/Documentation/gitrevisions.txt\n@@ -16,8 +16,8 @@ DESCRIPTION\n Many Git commands take revision parameters as arguments. Depending on\n the command, they denote a specific commit or, for commands which\n walk the revision graph (such as linkgit:git-log[1]), all commits which are\n-reachable from that commit. In the latter case one can also specify a\n-range of revisions explicitly.\n+reachable from that commit. For commands that walk the revision graph one can\n+also specify a range of revisions explicitly.\n \n In addition, some Git commands (such as linkgit:git-show[1]) also take\n revision parameters which denote other objects than commits, e.g. blobs\n-- \n2.9.0.windows.1\n\n"},{"id":"291868","messageId":"20160720211007.5520-4-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160720211007.5520-1-philipoakley@iee.org","subject":"[PATCH v4 3/8] doc: show the actual left, right, and boundary marks","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-07-20T21:10:02Z","receivedAt":"2016-07-20T21:10:44Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Signed-off-by: Philip Oakley \n---\nFound while checking the 'symmetric difference' documentation\n---\n Documentation/pretty-formats.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt\nindex 29b19b9..10719e1 100644\n--- a/Documentation/pretty-formats.txt\n+++ b/Documentation/pretty-formats.txt\n@@ -166,7 +166,7 @@ endif::git-rev-list[]\n respecting the `auto` settings of the former if we are going to a\n terminal). `auto` alone (i.e. `%C(auto)`) will turn on auto coloring\n on the next placeholders until the color is switched again.\n-- '%m': left, right or boundary mark\n+- '%m': left (`<`), right (`>`) or boundary (`-`) mark\n - '%n': newline\n - '%%': a raw '%'\n - '%x00': print a byte from a hex code\n-- \n2.9.0.windows.1\n\n"},{"id":"291869","messageId":"20160720211007.5520-2-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160720211007.5520-1-philipoakley@iee.org","subject":"[PATCH v4 1/8] doc: use 'symmetric difference' consistently","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-07-20T21:10:00Z","receivedAt":"2016-07-20T21:10:47Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Signed-off-by: Philip Oakley \n---\n Documentation/gitk.txt | 2 +-\n Documentation/rev-list-options.txt | 4 ++--\n 2 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/gitk.txt b/Documentation/gitk.txt\nindex 6ade002..6c3eb15 100644\n--- a/Documentation/gitk.txt\n+++ b/Documentation/gitk.txt\n@@ -70,7 +70,7 @@ linkgit:git-rev-list[1] for a complete list.\n \n --left-right::\n \n-\tMark which side of a symmetric diff a commit is reachable\n+\tMark which side of a symmetric difference a commit is reachable\n \tfrom. Commits from the left side are prefixed with a `<`\n \tsymbol and those from the right with a `>` symbol.\n \ndiff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt\nindex 4f009d4..6dc0bb0 100644\n--- a/Documentation/rev-list-options.txt\n+++ b/Documentation/rev-list-options.txt\n@@ -225,7 +225,7 @@ excluded from the output.\n \n --left-only::\n --right-only::\n-\tList only commits on the respective side of a symmetric range,\n+\tList only commits on the respective side of a symmetric difference,\n \ti.e. only those which would be marked `<` resp. `>` by\n \t`--left-right`.\n +\n@@ -766,7 +766,7 @@ ifdef::git-rev-list[]\n endif::git-rev-list[]\n \n --left-right::\n-\tMark which side of a symmetric diff a commit is reachable from.\n+\tMark which side of a symmetric difference a commit is reachable from.\n \tCommits from the left side are prefixed with `<` and those from\n \tthe right with `>`. If combined with `--boundary`, those\n \tcommits are prefixed with `-`.\n-- \n2.9.0.windows.1\n\n"},{"id":"291870","messageId":"20160720211007.5520-6-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160720211007.5520-1-philipoakley@iee.org","subject":"[PATCH v4 5/8] doc: gitrevisions - use 'reachable' in page description","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-07-20T21:10:04Z","receivedAt":"2016-07-20T21:10:50Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Signed-off-by: Philip Oakley \n---\n Documentation/gitrevisions.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/gitrevisions.txt b/Documentation/gitrevisions.txt\nindex e903eb7..33039c6 100644\n--- a/Documentation/gitrevisions.txt\n+++ b/Documentation/gitrevisions.txt\n@@ -15,8 +15,8 @@ DESCRIPTION\n \n Many Git commands take revision parameters as arguments. Depending on\n the command, they denote a specific commit or, for commands which\n-walk the revision graph (such as linkgit:git-log[1]), all commits which can\n-be reached from that commit. In the latter case one can also specify a\n+walk the revision graph (such as linkgit:git-log[1]), all commits which are\n+reachable from that commit. In the latter case one can also specify a\n range of revisions explicitly.\n \n In addition, some Git commands (such as linkgit:git-show[1]) also take\n-- \n2.9.0.windows.1\n\n"},{"id":"291871","messageId":"20160720211007.5520-5-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160720211007.5520-1-philipoakley@iee.org","subject":"[PATCH v4 4/8] doc: give headings for the two and three dot notations","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-07-20T21:10:03Z","receivedAt":"2016-07-20T21:10:53Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"While there, also break out the other shorthand notations and\nadd a title for the revision range summary (which also appears\nin git-rev-parse, so keep it mixed case).\n\nSigned-off-by: Philip Oakley \n---\n Documentation/revisions.txt | 58 ++++++++++++++++++++++++++++-----------------\n 1 file changed, 36 insertions(+), 22 deletions(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 6e9cd41..5b37283 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -242,35 +242,49 @@ specifying a single revision with the notation described in the\n previous section means the set of commits reachable from that\n commit, following the commit ancestry chain.\n \n-To exclude commits reachable from a commit, a prefix '{caret}'\n-notation is used. E.g. '{caret}r1 r2' means commits reachable\n-from 'r2' but exclude the ones reachable from 'r1'.\n-\n-This set operation appears so often that there is a shorthand\n-for it. When you have two commits 'r1' and 'r2' (named according\n-to the syntax explained in SPECIFYING REVISIONS above), you can ask\n-for commits that are reachable from r2 excluding those that are reachable\n-from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.\n-\n-A similar notation 'r1\\...r2' is called symmetric difference\n-of 'r1' and 'r2' and is defined as\n-'r1 r2 --not $(git merge-base --all r1 r2)'.\n-It is the set of commits that are reachable from either one of\n-'r1' (left side) or 'r2' (right side) but not from both.\n-\n-In these two shorthands, you can omit one end and let it default to HEAD.\n+Commit Exclusions\n+~~~~~~~~~~~~~~~~~\n+\n+'{caret}' (caret) Notation::\n+ To exclude commits reachable from a commit, a prefix '{caret}'\n+ notation is used. E.g. '{caret}r1 r2' means commits reachable\n+ from 'r2' but exclude the ones reachable from 'r1'.\n+\n+Dotted Range Notations\n+~~~~~~~~~~~~~~~~~~~~~~\n+\n+The '..' (two-dot) Range Notation::\n+ The '{caret}r1 r2' set operation appears so often that there is a shorthand\n+ for it. When you have two commits 'r1' and 'r2' (named according\n+ to the syntax explained in SPECIFYING REVISIONS above), you can ask\n+ for commits that are reachable from r2 excluding those that are reachable\n+ from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.\n+\n+The '...' (three dot) Symmetric Difference Notation::\n+ A similar notation 'r1\\...r2' is called symmetric difference\n+ of 'r1' and 'r2' and is defined as\n+ 'r1 r2 --not $(git merge-base --all r1 r2)'.\n+ It is the set of commits that are reachable from either one of\n+ 'r1' (left side) or 'r2' (right side) but not from both.\n+\n+In these two shorthand notations, you can omit one end and let it default to HEAD.\n For example, 'origin..' is a shorthand for 'origin..HEAD' and asks \"What\n did I do since I forked from the origin branch?\" Similarly, '..origin'\n is a shorthand for 'HEAD..origin' and asks \"What did the origin do since\n I forked from them?\" Note that '..' would mean 'HEAD..HEAD' which is an\n empty range that is both reachable and unreachable from HEAD.\n \n-Two other shorthands for naming a set that is formed by a commit\n-and its parent commits exist. The 'r1{caret}@' notation means all\n-parents of 'r1'. 'r1{caret}!' includes commit 'r1' but excludes\n-all of its parents.\n+Special '{caret}' Shorthand Notations\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+Two other shorthands exist, particularly useful for merge commits, is\n+for naming a set that is formed by a commit and its parent commits.\n \n-To summarize:\n+The 'r1{caret}@' notation means all parents of 'r1'.\n+\n+'r1{caret}!' includes commit 'r1' but excludes all of its parents.\n+\n+Revision Range Summary\n+----------------------\n \n ''::\n \tInclude commits that are reachable from (i.e. ancestors of)\n-- \n2.9.0.windows.1\n\n"},{"id":"291889","messageId":"xmqq4m7kc5md.fsf@gitster.mtv.corp.google.com","threadId":"42687","inReplyTo":"20160720211007.5520-1-philipoakley@iee.org","subject":"Re: [PATCH v4 0/8] Name for A..B ranges?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-07-20T22:22:02Z","receivedAt":"2016-07-20T22:22:12Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley writes:\n\n> No change in the number of patches. Interdiff below.\n>\n> The patches carefully tease out the clarification of\n> reachability. Reachability is defined relative the ancestry chain thus\n> (hopefully) avoiding misunderstandings.\n>\n> The final patch updates the summary examples, and the tricky (for the\n> untutored reader) two dots case of a linear development where r1..r2\n> excludes r1 itself.\n\nAll looked sensible and each focused on a single issue and fixing it\nwell. Done very nicely.\n\nThanks. Will (re)queue, wait for a few days for further comments\nand let's merge it to 'next'.\n\n"},{"id":"291918","messageId":"5790DF64.8030603@xiplink.com","threadId":"42687","inReplyTo":"20160720211007.5520-5-philipoakley@iee.org","subject":"Re: [PATCH v4 4/8] doc: give headings for the two and three dot notations","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2016-07-21T14:42:44Z","receivedAt":"2016-07-21T14:48:57Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"On 2016-07-20 05:10 PM, Philip Oakley wrote:\n> While there, also break out the other shorthand notations and\n> add a title for the revision range summary (which also appears\n> in git-rev-parse, so keep it mixed case).\n>\n> Signed-off-by: Philip Oakley \n> ---\n> Documentation/revisions.txt | 58 ++++++++++++++++++++++++++++-----------------\n> 1 file changed, 36 insertions(+), 22 deletions(-)\n>\n> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\n> index 6e9cd41..5b37283 100644\n> --- a/Documentation/revisions.txt\n> +++ b/Documentation/revisions.txt\n> @@ -242,35 +242,49 @@ specifying a single revision with the notation described in the\n> previous section means the set of commits reachable from that\n> commit, following the commit ancestry chain.\n>\n> -To exclude commits reachable from a commit, a prefix '{caret}'\n> -notation is used. E.g. '{caret}r1 r2' means commits reachable\n> -from 'r2' but exclude the ones reachable from 'r1'.\n> -\n> -This set operation appears so often that there is a shorthand\n> -for it. When you have two commits 'r1' and 'r2' (named according\n> -to the syntax explained in SPECIFYING REVISIONS above), you can ask\n> -for commits that are reachable from r2 excluding those that are reachable\n> -from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.\n> -\n> -A similar notation 'r1\\...r2' is called symmetric difference\n> -of 'r1' and 'r2' and is defined as\n> -'r1 r2 --not $(git merge-base --all r1 r2)'.\n> -It is the set of commits that are reachable from either one of\n> -'r1' (left side) or 'r2' (right side) but not from both.\n> -\n> -In these two shorthands, you can omit one end and let it default to HEAD.\n> +Commit Exclusions\n> +~~~~~~~~~~~~~~~~~\n> +\n> +'{caret}' (caret) Notation::\n> + To exclude commits reachable from a commit, a prefix '{caret}'\n> + notation is used. E.g. '{caret}r1 r2' means commits reachable\n> + from 'r2' but exclude the ones reachable from 'r1'.\n> +\n> +Dotted Range Notations\n> +~~~~~~~~~~~~~~~~~~~~~~\n> +\n> +The '..' (two-dot) Range Notation::\n> + The '{caret}r1 r2' set operation appears so often that there is a shorthand\n> + for it. When you have two commits 'r1' and 'r2' (named according\n> + to the syntax explained in SPECIFYING REVISIONS above), you can ask\n> + for commits that are reachable from r2 excluding those that are reachable\n> + from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.\n> +\n> +The '...' (three dot) Symmetric Difference Notation::\n> + A similar notation 'r1\\...r2' is called symmetric difference\n\ns/called/called the/\n\n> + of 'r1' and 'r2' and is defined as\n> + 'r1 r2 --not $(git merge-base --all r1 r2)'.\n> + It is the set of commits that are reachable from either one of\n> + 'r1' (left side) or 'r2' (right side) but not from both.\n> +\n> +In these two shorthand notations, you can omit one end and let it default to HEAD.\n> For example, 'origin..' is a shorthand for 'origin..HEAD' and asks \"What\n> did I do since I forked from the origin branch?\" Similarly, '..origin'\n> is a shorthand for 'HEAD..origin' and asks \"What did the origin do since\n> I forked from them?\" Note that '..' would mean 'HEAD..HEAD' which is an\n> empty range that is both reachable and unreachable from HEAD.\n>\n> -Two other shorthands for naming a set that is formed by a commit\n> -and its parent commits exist. The 'r1{caret}@' notation means all\n> -parents of 'r1'. 'r1{caret}!' includes commit 'r1' but excludes\n> -all of its parents.\n> +Special '{caret}' Shorthand Notations\n> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nSorry, but this header also does not render properly in the man page. \nMaybe just \"Special {caret} Shorthand Notations\"? (But read on!)\n\n> +Two other shorthands exist, particularly useful for merge commits, is\n> +for naming a set that is formed by a commit and its parent commits.\n>\n> -To summarize:\n> +The 'r1{caret}@' notation means all parents of 'r1'.\n> +\n> +'r1{caret}!' includes commit 'r1' but excludes all of its parents.\n\nMy immediate thought upon reading this is \"Why not just use 'r1'?\" I \nthink the answer is \"This truncates the range.\" So, for example, \"git \nlog r1\" shows you r1 and its ancestors, while \"git log r1^!\" only shows \nyou r1. I think you should add this example, or something similar.\n\nBut, really, this means that the notation is another \"Commit Exclusion\" \nand properly belongs in that section.\n\nThat makes this \"Special Notations\" section rather thin. I suggest \nmoving a slightly expanded ^@ description to a small subsection \njust before Commit Exclusions, and deleting the Special Notations \nsection altogether. So add something like this:\n\n\tCommit Parents\n\t~~~~~~~~~~~~~~\n\n\t'{caret}@' Notation::\n\t The 'r1{caret}@' notation means all parents of 'r1',\n\t excluding 'r1' itself.\n\nThis smoothly re-introduces the notion of parents for readers who \nskipped to this section, and helps them make sense of the ^! notation.\n\nPlus there's no longer anything \"special\" about any of the syntax.\n\n> +\n> +Revision Range Summary\n> +----------------------\n\nSorry, but the man page renders this in all caps. I really think you \nshould use ~~~~~~~~~ here.\n\n\t\tM.\n\n"},{"id":"291933","messageId":"9B0B8E2D61D34BFEB8FC3F30EB23437C@PhilipOakley","threadId":"42687","inReplyTo":"5790DF64.8030603@xiplink.com","subject":"Re: [PATCH v4 4/8] doc: give headings for the two and three dot notations","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-07-21T19:54:53Z","receivedAt":"2016-07-21T19:55:00Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Marc Branchaud\" \n> On 2016-07-20 05:10 PM, Philip Oakley wrote:\n>> While there, also break out the other shorthand notations and\n>> add a title for the revision range summary (which also appears\n>> in git-rev-parse, so keep it mixed case).\n>>\n>> Signed-off-by: Philip Oakley \n>> ---\n>> Documentation/revisions.txt | 58 \n>> ++++++++++++++++++++++++++++-----------------\n>> 1 file changed, 36 insertions(+), 22 deletions(-)\n>>\n>> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\n>> index 6e9cd41..5b37283 100644\n>> --- a/Documentation/revisions.txt\n>> +++ b/Documentation/revisions.txt\n>> @@ -242,35 +242,49 @@ specifying a single revision with the notation \n>> described in the\n>> previous section means the set of commits reachable from that\n>> commit, following the commit ancestry chain.\n>>\n>> -To exclude commits reachable from a commit, a prefix '{caret}'\n>> -notation is used. E.g. '{caret}r1 r2' means commits reachable\n>> -from 'r2' but exclude the ones reachable from 'r1'.\n>> -\n>> -This set operation appears so often that there is a shorthand\n>> -for it. When you have two commits 'r1' and 'r2' (named according\n>> -to the syntax explained in SPECIFYING REVISIONS above), you can ask\n>> -for commits that are reachable from r2 excluding those that are \n>> reachable\n>> -from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.\n>> -\n>> -A similar notation 'r1\\...r2' is called symmetric difference\n>> -of 'r1' and 'r2' and is defined as\n>> -'r1 r2 --not $(git merge-base --all r1 r2)'.\n>> -It is the set of commits that are reachable from either one of\n>> -'r1' (left side) or 'r2' (right side) but not from both.\n>> -\n>> -In these two shorthands, you can omit one end and let it default to \n>> HEAD.\n>> +Commit Exclusions\n>> +~~~~~~~~~~~~~~~~~\n>> +\n>> +'{caret}' (caret) Notation::\n>> + To exclude commits reachable from a commit, a prefix '{caret}'\n>> + notation is used. E.g. '{caret}r1 r2' means commits reachable\n>> + from 'r2' but exclude the ones reachable from 'r1'.\n>> +\n>> +Dotted Range Notations\n>> +~~~~~~~~~~~~~~~~~~~~~~\n>> +\n>> +The '..' (two-dot) Range Notation::\n>> + The '{caret}r1 r2' set operation appears so often that there is a \n>> shorthand\n>> + for it. When you have two commits 'r1' and 'r2' (named according\n>> + to the syntax explained in SPECIFYING REVISIONS above), you can ask\n>> + for commits that are reachable from r2 excluding those that are \n>> reachable\n>> + from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.\n>> +\n>> +The '...' (three dot) Symmetric Difference Notation::\n>> + A similar notation 'r1\\...r2' is called symmetric difference\n>\n> s/called/called the/\n\nThe wording is the original ;-) Can change.\n\n>\n>> + of 'r1' and 'r2' and is defined as\n>> + 'r1 r2 --not $(git merge-base --all r1 r2)'.\n>> + It is the set of commits that are reachable from either one of\n>> + 'r1' (left side) or 'r2' (right side) but not from both.\n>> +\n>> +In these two shorthand notations, you can omit one end and let it \n>> default to HEAD.\n>> For example, 'origin..' is a shorthand for 'origin..HEAD' and asks \n>> \"What\n>> did I do since I forked from the origin branch?\" Similarly, '..origin'\n>> is a shorthand for 'HEAD..origin' and asks \"What did the origin do \n>> since\n>> I forked from them?\" Note that '..' would mean 'HEAD..HEAD' which is \n>> an\n>> empty range that is both reachable and unreachable from HEAD.\n>>\n>> -Two other shorthands for naming a set that is formed by a commit\n>> -and its parent commits exist. The 'r1{caret}@' notation means all\n>> -parents of 'r1'. 'r1{caret}!' includes commit 'r1' but excludes\n>> -all of its parents.\n>> +Special '{caret}' Shorthand Notations\n>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n>\n> Sorry, but this header also does not render properly in the man page. \n> Maybe just \"Special {caret} Shorthand Notations\"? (But read on!)\n\nrendered fine on the MYS2 man invocation - I had had to add the prefix \nto the quoted title to make it work.\n\nWhat went wrong for you? (I'll read on)\n\n\n>\n>> +Two other shorthands exist, particularly useful for merge commits, is\n>> +for naming a set that is formed by a commit and its parent commits.\n>>\n>> -To summarize:\n>> +The 'r1{caret}@' notation means all parents of 'r1'.\n>> +\n>> +'r1{caret}!' includes commit 'r1' but excludes all of its parents.\n>\n> My immediate thought upon reading this is \"Why not just use 'r1'?\" I \n> think the answer is \"This truncates the range.\" So, for example, \"git log \n> r1\" shows you r1 and its ancestors, while \"git log r1^!\" only shows you \n> r1. I think you should add this example, or something similar.\n>\n\nI'd also asked that question in one of my replies earlier $gmane/299849. I \nwas then able to determine that it was a width wide 'range' covering \nmulti-parent situations.\n\nIdentifying an example could be good if it was succinct and explanatory.\n\n$ git rev-parse 6c71a849^!\n> But, really, this means that the notation is another \"Commit Exclusion\" \n> and properly belongs in that section.\n\nI think it's bigger than that.\n>\n> That makes this \"Special Notations\" section rather thin. I suggest moving \n> a slightly expanded ^@ description to a small subsection just before \n> Commit Exclusions, and deleting the Special Notations section altogether. \n> So add something like this:\n>\n> Commit Parents\n> ~~~~~~~~~~~~~~\n\nIt's a bit better, but I'm still not sure it really tells the story, maybe \n\"Handling Commit Parent(s)\", with that subtle extra emphasis!\n\n>\n> '{caret}@' Notation::\n> The 'r1{caret}@' notation means all parents of 'r1',\n> excluding 'r1' itself.\n>\n> This smoothly re-introduces the notion of parents for readers who skipped \n> to this section, and helps them make sense of the ^! notation.\n>\n> Plus there's no longer anything \"special\" about any of the syntax.\n>\n>> +\n>> +Revision Range Summary\n>> +----------------------\n>\n> Sorry, but the man page renders this in all caps. I really think you \n> should use ~~~~~~~~~ here.\n\nYes, the man page formating is annoying relative to the web page formatting \nwhich it has to be compared against.\n\nI felt that it was at a higher level than the other sub-headings, and that \nusing mixed case did work well on the html (the Git for Windows standard).\n\nAt the moment I'm minded to keep it as is unless others chime in.\n\n>\n> M.\n>\nI'll be away till mid next week.\n--\nPhilip \n\n"},{"id":"291937","messageId":"57913C97.1030001@xiplink.com","threadId":"42687","inReplyTo":"9B0B8E2D61D34BFEB8FC3F30EB23437C@PhilipOakley","subject":"Re: [PATCH v4 4/8] doc: give headings for the two and three dot notations","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2016-07-21T21:20:23Z","receivedAt":"2016-07-21T21:20:30Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"On 2016-07-21 03:54 PM, Philip Oakley wrote:\n> From: \"Marc Branchaud\" \n>> On 2016-07-20 05:10 PM, Philip Oakley wrote:\n>>> While there, also break out the other shorthand notations and\n>>> add a title for the revision range summary (which also appears\n>>> in git-rev-parse, so keep it mixed case).\n>>>\n>>> Signed-off-by: Philip Oakley \n>>> ---\n>>> Documentation/revisions.txt | 58\n>>> ++++++++++++++++++++++++++++-----------------\n>>> 1 file changed, 36 insertions(+), 22 deletions(-)\n>>>\n>>> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\n>>> index 6e9cd41..5b37283 100644\n>>> --- a/Documentation/revisions.txt\n>>> +++ b/Documentation/revisions.txt\n>>> @@ -242,35 +242,49 @@ specifying a single revision with the notation\n>>> described in the\n>>> previous section means the set of commits reachable from that\n>>> commit, following the commit ancestry chain.\n>>>\n>>> -To exclude commits reachable from a commit, a prefix '{caret}'\n>>> -notation is used. E.g. '{caret}r1 r2' means commits reachable\n>>> -from 'r2' but exclude the ones reachable from 'r1'.\n>>> -\n>>> -This set operation appears so often that there is a shorthand\n>>> -for it. When you have two commits 'r1' and 'r2' (named according\n>>> -to the syntax explained in SPECIFYING REVISIONS above), you can ask\n>>> -for commits that are reachable from r2 excluding those that are\n>>> reachable\n>>> -from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.\n>>> -\n>>> -A similar notation 'r1\\...r2' is called symmetric difference\n>>> -of 'r1' and 'r2' and is defined as\n>>> -'r1 r2 --not $(git merge-base --all r1 r2)'.\n>>> -It is the set of commits that are reachable from either one of\n>>> -'r1' (left side) or 'r2' (right side) but not from both.\n>>> -\n>>> -In these two shorthands, you can omit one end and let it default to\n>>> HEAD.\n>>> +Commit Exclusions\n>>> +~~~~~~~~~~~~~~~~~\n>>> +\n>>> +'{caret}' (caret) Notation::\n>>> + To exclude commits reachable from a commit, a prefix '{caret}'\n>>> + notation is used. E.g. '{caret}r1 r2' means commits reachable\n>>> + from 'r2' but exclude the ones reachable from 'r1'.\n>>> +\n>>> +Dotted Range Notations\n>>> +~~~~~~~~~~~~~~~~~~~~~~\n>>> +\n>>> +The '..' (two-dot) Range Notation::\n>>> + The '{caret}r1 r2' set operation appears so often that there is a\n>>> shorthand\n>>> + for it. When you have two commits 'r1' and 'r2' (named according\n>>> + to the syntax explained in SPECIFYING REVISIONS above), you can ask\n>>> + for commits that are reachable from r2 excluding those that are\n>>> reachable\n>>> + from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.\n>>> +\n>>> +The '...' (three dot) Symmetric Difference Notation::\n>>> + A similar notation 'r1\\...r2' is called symmetric difference\n>>\n>> s/called/called the/\n>\n> The wording is the original ;-) Can change.\n>\n>>\n>>> + of 'r1' and 'r2' and is defined as\n>>> + 'r1 r2 --not $(git merge-base --all r1 r2)'.\n>>> + It is the set of commits that are reachable from either one of\n>>> + 'r1' (left side) or 'r2' (right side) but not from both.\n>>> +\n>>> +In these two shorthand notations, you can omit one end and let it\n>>> default to HEAD.\n>>> For example, 'origin..' is a shorthand for 'origin..HEAD' and asks\n>>> \"What\n>>> did I do since I forked from the origin branch?\" Similarly,\n>>> '..origin'\n>>> is a shorthand for 'HEAD..origin' and asks \"What did the origin do\n>>> since\n>>> I forked from them?\" Note that '..' would mean 'HEAD..HEAD' which\n>>> is an\n>>> empty range that is both reachable and unreachable from HEAD.\n>>>\n>>> -Two other shorthands for naming a set that is formed by a commit\n>>> -and its parent commits exist. The 'r1{caret}@' notation means all\n>>> -parents of 'r1'. 'r1{caret}!' includes commit 'r1' but excludes\n>>> -all of its parents.\n>>> +Special '{caret}' Shorthand Notations\n>>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n>>\n>> Sorry, but this header also does not render properly in the man page.\n>> Maybe just \"Special {caret} Shorthand Notations\"? (But read on!)\n>\n> rendered fine on the MYS2 man invocation - I had had to add the \n> prefix to the quoted title to make it work.\n>\n> What went wrong for you? (I'll read on)\n\nOnly the word \"Special\" is emphasized (in bold). The rest of the header \nis plain.\n\nI'm using asciidoc 8.6.9, so I'm likely suffering from the bug Peff \nidentified.\n\n>>\n>>> +Two other shorthands exist, particularly useful for merge commits, is\n>>> +for naming a set that is formed by a commit and its parent commits.\n>>>\n>>> -To summarize:\n>>> +The 'r1{caret}@' notation means all parents of 'r1'.\n>>> +\n>>> +'r1{caret}!' includes commit 'r1' but excludes all of its parents.\n>>\n>> My immediate thought upon reading this is \"Why not just use 'r1'?\" I\n>> think the answer is \"This truncates the range.\" So, for example, \"git\n>> log r1\" shows you r1 and its ancestors, while \"git log r1^!\" only\n>> shows you r1. I think you should add this example, or something similar.\n>>\n>\n> I'd also asked that question in one of my replies earlier $gmane/299849.\n> I was then able to determine that it was a width wide 'range' covering\n> multi-parent situations.\n\nObviously, I see it more an anti-range. You're never going to get more \nthan a single commit with this notation.\n\n> Identifying an example could be good if it was succinct and explanatory.\n\nWhat do you think of my example?\n\n> $ git rev-parse 6c71a849^!\n>> But, really, this means that the notation is another \"Commit\n>> Exclusion\" and properly belongs in that section.\n>\n> I think it's bigger than that.\n>>\n>> That makes this \"Special Notations\" section rather thin. I suggest\n>> moving a slightly expanded ^@ description to a small subsection\n>> just before Commit Exclusions, and deleting the Special Notations\n>> section altogether. So add something like this:\n>>\n>> Commit Parents\n>> ~~~~~~~~~~~~~~\n>\n> It's a bit better, but I'm still not sure it really tells the story,\n> maybe \"Handling Commit Parent(s)\", with that subtle extra emphasis!\n\n\"Specifying Commit Parents\"? Any of these work for me, really.\n\n>>\n>> '{caret}@' Notation::\n>> The 'r1{caret}@' notation means all parents of 'r1',\n>> excluding 'r1' itself.\n>>\n>> This smoothly re-introduces the notion of parents for readers who\n>> skipped to this section, and helps them make sense of the ^!\n>> notation.\n>>\n>> Plus there's no longer anything \"special\" about any of the syntax.\n>>\n>>> +\n>>> +Revision Range Summary\n>>> +----------------------\n>>\n>> Sorry, but the man page renders this in all caps. I really think you\n>> should use ~~~~~~~~~ here.\n>\n> Yes, the man page formating is annoying relative to the web page\n> formatting which it has to be compared against.\n>\n> I felt that it was at a higher level than the other sub-headings, and\n> that using mixed case did work well on the html (the Git for Windows\n> standard).\n\nIMHO it has to look like it's part of the SPECIFYING RANGES section. It \nneed not be higher than the other subsections though.\n\n> At the moment I'm minded to keep it as is unless others chime in.\n\nI'll bow to the will of the majority.\n\n>>\n>> M.\n>>\n> I'll be away till mid next week.\n\nAs will I!\n\n\t\tM.\n\n"},{"id":"292021","messageId":"xmqqoa5p8f56.fsf@gitster.mtv.corp.google.com","threadId":"42687","inReplyTo":"20160720211007.5520-5-philipoakley@iee.org","subject":"Re: [PATCH v4 4/8] doc: give headings for the two and three dot notations","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-07-22T22:46:45Z","receivedAt":"2016-07-22T22:46:53Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley writes:\n\n> +Special '{caret}' Shorthand Notations\n> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n> +Two other shorthands exist, particularly useful for merge commits, is\n> +for naming a set that is formed by a commit and its parent commits.\n\nAs these are not all that \"special\", how about retitling this\nsection as:\n\n\tOther Shorthand Notations\n ~~~~~~~~~~~~~~~~~~~~~~~~~\n\n\n> -To summarize:\n> +The 'r1{caret}@' notation means all parents of 'r1'.\n> +\n> +'r1{caret}!' includes commit 'r1' but excludes all of its parents.\n> +\n> +Revision Range Summary\n> +----------------------\n> \n> ''::\n> \tInclude commits that are reachable from (i.e. ancestors of)\n"},{"id":"298792","messageId":"20160811215035.4108-1-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160720211007.5520-1-philipoakley@iee.org","subject":"[PATCH v5 00/12] Update git revisions","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-11T21:50:23Z","receivedAt":"2016-08-11T21:50:49Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"This has grown like topsy from a little two patch series that tried to\nname the 2-dots notation [1] into this extended set of tweaks.\n\nAs documentation can be rather personal, I've split out each small change\nso each can be individually justified.\n\nSince V4, I've confirmed that the format breaking issue is that we cannot\nquote code in headings in the man page layout - ultimately it's a docbook\ndecision, and follows the line of analysis Peff identified (see commentary\nin the patch).\n\nIn addition the multi-parent notations have been clarified and extended.\n\nThus the old patch 4 has been split into three. The first three patches are\nunchanged. The following 4 patches are also unchanged.\n\nFinally, at the end an extra 2 patches are added to build up the examples by\nincluding details of the notation expansions.\n\nThis updates po/range-doc (2016-07-20) 8 commits.\n\nHopefully my updated workflow will get the right patches to the right people.\n\n[1] https://public-inbox.org/git/0648000B273C412AB7140AE959EBC99A%40PhilipOakley/\n\nPhilip Oakley (12):\n doc: use 'symmetric difference' consistently\n doc: revisions - name the left and right sides\n doc: show the actual left, right, and boundary marks\n doc: revisions: give headings for the two and three dot notations\n doc: revisions: extra clarification of ^! notation effects\n doc: revisions: single vs multi-parent notation comparison\n doc: gitrevisions - use 'reachable' in page description\n doc: gitrevisions - clarify 'latter case' is revision walk\n doc: revisions - define `reachable`\n doc: revisions - clarify reachability examples\n doc: revisions: show revision expansion in examples\n doc: revisions: sort examples and fix alignment of the unchanged\n\n Documentation/gitk.txt | 2 +-\n Documentation/gitrevisions.txt | 6 +-\n Documentation/pretty-formats.txt | 2 +-\n Documentation/rev-list-options.txt | 4 +-\n Documentation/revisions.txt | 121 +++++++++++++++++++++++--------------\n 5 files changed, 84 insertions(+), 51 deletions(-)\n\n-- \n2.9.0.windows.1\n\n"},{"id":"298793","messageId":"20160811215035.4108-2-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160811215035.4108-1-philipoakley@iee.org","subject":"[PATCH v5 01/12] doc: use 'symmetric difference' consistently","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-11T21:50:24Z","receivedAt":"2016-08-11T21:51:07Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Signed-off-by: Philip Oakley \n---\nunchanged\n---\n Documentation/gitk.txt | 2 +-\n Documentation/rev-list-options.txt | 4 ++--\n 2 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/gitk.txt b/Documentation/gitk.txt\nindex 6ade002..6c3eb15 100644\n--- a/Documentation/gitk.txt\n+++ b/Documentation/gitk.txt\n@@ -70,7 +70,7 @@ linkgit:git-rev-list[1] for a complete list.\n \n --left-right::\n \n-\tMark which side of a symmetric diff a commit is reachable\n+\tMark which side of a symmetric difference a commit is reachable\n \tfrom. Commits from the left side are prefixed with a `<`\n \tsymbol and those from the right with a `>` symbol.\n \ndiff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt\nindex 4f009d4..6dc0bb0 100644\n--- a/Documentation/rev-list-options.txt\n+++ b/Documentation/rev-list-options.txt\n@@ -225,7 +225,7 @@ excluded from the output.\n \n --left-only::\n --right-only::\n-\tList only commits on the respective side of a symmetric range,\n+\tList only commits on the respective side of a symmetric difference,\n \ti.e. only those which would be marked `<` resp. `>` by\n \t`--left-right`.\n +\n@@ -766,7 +766,7 @@ ifdef::git-rev-list[]\n endif::git-rev-list[]\n \n --left-right::\n-\tMark which side of a symmetric diff a commit is reachable from.\n+\tMark which side of a symmetric difference a commit is reachable from.\n \tCommits from the left side are prefixed with `<` and those from\n \tthe right with `>`. If combined with `--boundary`, those\n \tcommits are prefixed with `-`.\n-- \n2.9.0.windows.1\n\n"},{"id":"298801","messageId":"83F54348B6A84659802AAA01F782F837@PhilipOakley","threadId":"42687","inReplyTo":"20160811215035.4108-1-philipoakley@iee.org","subject":"Re: [PATCH v5 00/12] Update git revisions","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-11T22:32:10Z","receivedAt":"2016-08-11T23:00:52Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"I'm having trouble with my ISP is not playing ball. only cover and patch 1 \nwere sent.\n\nWill retry with alternate service.\n\nPhilip\n----- Original Message ----- \nFrom: \"Philip Oakley\" \nSent: Thursday, August 11, 2016 10:50 PM\nSubject: [PATCH v5 00/12] Update git revisions\n\n\n> This has grown like topsy from a little two patch series that tried to\n> name the 2-dots notation [1] into this extended set of tweaks.\n>\n> As documentation can be rather personal, I've split out each small change\n> so each can be individually justified.\n>\n> Since V4, I've confirmed that the format breaking issue is that we cannot\n> quote code in headings in the man page layout - ultimately it's a docbook\n> decision, and follows the line of analysis Peff identified (see commentary\n> in the patch).\n>\n> In addition the multi-parent notations have been clarified and extended.\n>\n> Thus the old patch 4 has been split into three. The first three patches \n> are\n> unchanged. The following 4 patches are also unchanged.\n>\n> Finally, at the end an extra 2 patches are added to build up the examples \n> by\n> including details of the notation expansions.\n>\n> This updates po/range-doc (2016-07-20) 8 commits.\n>\n> Hopefully my updated workflow will get the right patches to the right \n> people.\n>\n> [1] \n> https://public-inbox.org/git/0648000B273C412AB7140AE959EBC99A%40PhilipOakley/\n>\n> Philip Oakley (12):\n> doc: use 'symmetric difference' consistently\n> doc: revisions - name the left and right sides\n> doc: show the actual left, right, and boundary marks\n> doc: revisions: give headings for the two and three dot notations\n> doc: revisions: extra clarification of ^! notation effects\n> doc: revisions: single vs multi-parent notation comparison\n> doc: gitrevisions - use 'reachable' in page description\n> doc: gitrevisions - clarify 'latter case' is revision walk\n> doc: revisions - define `reachable`\n> doc: revisions - clarify reachability examples\n> doc: revisions: show revision expansion in examples\n> doc: revisions: sort examples and fix alignment of the unchanged\n>\n> Documentation/gitk.txt | 2 +-\n> Documentation/gitrevisions.txt | 6 +-\n> Documentation/pretty-formats.txt | 2 +-\n> Documentation/rev-list-options.txt | 4 +-\n> Documentation/revisions.txt | 121 \n> +++++++++++++++++++++++--------------\n> 5 files changed, 84 insertions(+), 51 deletions(-)\n>\n> -- \n> 2.9.0.windows.1\n>\n>\n> \n\n"},{"id":"298802","messageId":"20160811230327.4416-1-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160720211007.5520-1-philipoakley@iee.org","subject":"[PATCH v5 00/12] Update git revisions","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-11T23:03:15Z","receivedAt":"2016-08-11T23:03:39Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"This has grown like topsy from a little two patch series that tried to\nname the 2-dots notation [1] into this extended set of tweaks.\n\nAs documentation can be rather personal, I've split out each small change\nso each can be individually justified.\n\nSince V4, I've confirmed that the format breaking issue is that we cannot\nquote code in headings in the man page layout - ultimately it's a docbook\ndecision, and follows the line of analysis Peff identified (see commentary\nin the patch).\n\nIn addition the multi-parent notations have been clarified and extended.\n\nThus the old patch 4 has been split into three. The first three patches are\nunchanged. The following 4 patches are also unchanged.\n\nFinally, at the end an extra 2 patches are added to build up the examples by\nincluding details of the notation expansions.\n\nThis updates po/range-doc (2016-07-20) 8 commits.\n\nHopefully my updated workflow will get the right patches to the right people.\n\n[1] https://public-inbox.org/git/0648000B273C412AB7140AE959EBC99A%40PhilipOakley/\n\nPhilip Oakley (12):\n doc: use 'symmetric difference' consistently\n doc: revisions - name the left and right sides\n doc: show the actual left, right, and boundary marks\n doc: revisions: give headings for the two and three dot notations\n doc: revisions: extra clarification of ^! notation effects\n doc: revisions: single vs multi-parent notation comparison\n doc: gitrevisions - use 'reachable' in page description\n doc: gitrevisions - clarify 'latter case' is revision walk\n doc: revisions - define `reachable`\n doc: revisions - clarify reachability examples\n doc: revisions: show revision expansion in examples\n doc: revisions: sort examples and fix alignment of the unchanged\n\n Documentation/gitk.txt | 2 +-\n Documentation/gitrevisions.txt | 6 +-\n Documentation/pretty-formats.txt | 2 +-\n Documentation/rev-list-options.txt | 4 +-\n Documentation/revisions.txt | 121 +++++++++++++++++++++++--------------\n 5 files changed, 84 insertions(+), 51 deletions(-)\n\n-- \n2.9.0.windows.1\n\n"},{"id":"298803","messageId":"20160811230327.4416-2-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160811230327.4416-1-philipoakley@iee.org","subject":"[PATCH v5 01/12] doc: use 'symmetric difference' consistently","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-11T23:03:16Z","receivedAt":"2016-08-11T23:03:43Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Signed-off-by: Philip Oakley \n---\nunchanged\n---\n Documentation/gitk.txt | 2 +-\n Documentation/rev-list-options.txt | 4 ++--\n 2 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/gitk.txt b/Documentation/gitk.txt\nindex 6ade002..6c3eb15 100644\n--- a/Documentation/gitk.txt\n+++ b/Documentation/gitk.txt\n@@ -70,7 +70,7 @@ linkgit:git-rev-list[1] for a complete list.\n \n --left-right::\n \n-\tMark which side of a symmetric diff a commit is reachable\n+\tMark which side of a symmetric difference a commit is reachable\n \tfrom. Commits from the left side are prefixed with a `<`\n \tsymbol and those from the right with a `>` symbol.\n \ndiff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt\nindex 4f009d4..6dc0bb0 100644\n--- a/Documentation/rev-list-options.txt\n+++ b/Documentation/rev-list-options.txt\n@@ -225,7 +225,7 @@ excluded from the output.\n \n --left-only::\n --right-only::\n-\tList only commits on the respective side of a symmetric range,\n+\tList only commits on the respective side of a symmetric difference,\n \ti.e. only those which would be marked `<` resp. `>` by\n \t`--left-right`.\n +\n@@ -766,7 +766,7 @@ ifdef::git-rev-list[]\n endif::git-rev-list[]\n \n --left-right::\n-\tMark which side of a symmetric diff a commit is reachable from.\n+\tMark which side of a symmetric difference a commit is reachable from.\n \tCommits from the left side are prefixed with `<` and those from\n \tthe right with `>`. If combined with `--boundary`, those\n \tcommits are prefixed with `-`.\n-- \n2.9.0.windows.1\n\n"},{"id":"298815","messageId":"20160812070749.2920-13-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160812070749.2920-1-philipoakley@iee.org","subject":"[PATCH v5 12/12] doc: revisions: sort examples and fix alignment of the unchanged","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-12T07:07:49Z","receivedAt":"2016-08-12T07:09:04Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"The previous commit adjusted the column alignment for revision\nexamples which show expansion. Fix the unchanged examples and sort\nthose that show expansions to the end of the list.\n\nSigned-off-by: Philip Oakley \n---\nnew\n---\n Documentation/revisions.txt | 12 ++++++------\n 1 file changed, 6 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex ac7dd8e..8d65986 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -329,14 +329,14 @@ Revision Range Summary\n Here are a handful of examples using the Loeliger illustration above:\n \n Args Expansion Selection\n- D G H D\n- D F G H I J D F\n- ^G D H D\n- ^D B E I J F B\n+ D G H D\n+ D F G H I J D F\n+ ^G D H D\n+ ^D B E I J F B\n+ ^D B C E I J F B C\n+ C I J F C\n B..C = ^B C C\n B...C = B ^F C G H D E B C\n- ^D B C E I J F B C\n- C I J F C\n C^@ = C^1\n = F I J F\n B^@ = B^1 B^2 B^3\n-- \n2.9.0.windows.1\n\n"},{"id":"298816","messageId":"20160812070749.2920-10-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160812070749.2920-1-philipoakley@iee.org","subject":"[PATCH v5 09/12] doc: revisions - define `reachable`","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-12T07:07:46Z","receivedAt":"2016-08-12T07:09:12Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Do not self-define `reachable`, which can lead to misunderstanding.\nInstead define `reachability` explictly.\n\nSigned-off-by: Philip Oakley \n---\nunchanged\n---\n Documentation/revisions.txt | 14 ++++++++++----\n 1 file changed, 10 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 934d071..238be45 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -237,10 +237,16 @@ SPECIFYING RANGES\n -----------------\n \n History traversing commands such as `git log` operate on a set\n-of commits, not just a single commit. To these commands,\n-specifying a single revision with the notation described in the\n-previous section means the set of commits reachable from that\n-commit, following the commit ancestry chain.\n+of commits, not just a single commit.\n+\n+For these commands,\n+specifying a single revision, using the notation described in the\n+previous section, means the set of commits `reachable` from the given\n+commit.\n+\n+A commit's reachable set is the commit itself and the commits in\n+its ancestry chain.\n+\n \n Commit Exclusions\n ~~~~~~~~~~~~~~~~~\n-- \n2.9.0.windows.1\n\n"},{"id":"298817","messageId":"20160812070749.2920-9-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160812070749.2920-1-philipoakley@iee.org","subject":"[PATCH v5 08/12] doc: gitrevisions - clarify 'latter case' is revision walk","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-12T07:07:45Z","receivedAt":"2016-08-12T07:09:31Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"The prior sentence has too many clauses for easy parsing.\nReplace 'the latter case' with a direct quote.\n\nSigned-off-by: Philip Oakley \n---\nunchanged\n---\n Documentation/gitrevisions.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/gitrevisions.txt b/Documentation/gitrevisions.txt\nindex 33039c6..27dec5b 100644\n--- a/Documentation/gitrevisions.txt\n+++ b/Documentation/gitrevisions.txt\n@@ -16,8 +16,8 @@ DESCRIPTION\n Many Git commands take revision parameters as arguments. Depending on\n the command, they denote a specific commit or, for commands which\n walk the revision graph (such as linkgit:git-log[1]), all commits which are\n-reachable from that commit. In the latter case one can also specify a\n-range of revisions explicitly.\n+reachable from that commit. For commands that walk the revision graph one can\n+also specify a range of revisions explicitly.\n \n In addition, some Git commands (such as linkgit:git-show[1]) also take\n revision parameters which denote other objects than commits, e.g. blobs\n-- \n2.9.0.windows.1\n\n"},{"id":"298818","messageId":"20160812070749.2920-12-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160812070749.2920-1-philipoakley@iee.org","subject":"[PATCH v5 11/12] doc: revisions: show revision expansion in examples","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-12T07:07:48Z","receivedAt":"2016-08-12T07:09:34Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"The revisions examples show the revison arguments and the selected\ncommits, but do not show the intermediate step of the expansion of\nthe special 'range' notations. Extend the examples, including an\nall-parents multi-parent merge commit example.\n\nSort the examples and fix the alignment for those unaffected\nin the next commit.\n\nSigned-off-by: Philip Oakley \n---\nnew\nCc: Jakub Narębski \n---\n Documentation/revisions.txt | 19 +++++++++++++------\n 1 file changed, 13 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 70864d5..ac7dd8e 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -326,16 +326,23 @@ Revision Range Summary\n as giving commit '' and then all its parents prefixed with\n '{caret}' to exclude them (and their ancestors).\n \n-Here are a handful of examples:\n+Here are a handful of examples using the Loeliger illustration above:\n \n+ Args Expansion Selection\n D G H D\n D F G H I J D F\n ^G D H D\n ^D B E I J F B\n- B..C C\n- B...C G H D E B C\n+ B..C = ^B C C\n+ B...C = B ^F C G H D E B C\n ^D B C E I J F B C\n C I J F C\n- C^@ I J F\n- C^! C\n- F^! D G H D F\n+ C^@ = C^1\n+ = F I J F\n+ B^@ = B^1 B^2 B^3\n+ = D E F D G H E F I J\n+ C^! = C ^C^1\n+ = C ^F C\n+ B^! = B ^B^1 ^B^2 ^B^3\n+ = B ^D ^E ^F B\n+ F^! D = F ^I ^J D G H D F\n-- \n2.9.0.windows.1\n\n"},{"id":"298819","messageId":"20160812070749.2920-7-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160812070749.2920-1-philipoakley@iee.org","subject":"[PATCH v5 06/12] doc: revisions: single vs multi-parent notation comparison","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-12T07:07:43Z","receivedAt":"2016-08-12T07:09:35Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Signed-off-by: Philip Oakley \n---\nnew\nJunio's final comment https://public-inbox.org/git/xmqqwpkq6b4d.fsf%40gitster.mtv.corp.google.com/\n---\n Documentation/revisions.txt | 4 ++++\n 1 file changed, 4 insertions(+)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 0b5044d..934d071 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -284,6 +284,10 @@ The 'r1{caret}@' notation means all parents of 'r1'.\n 'r1{caret}!' notation includes commit 'r1' but excludes all of its parents.\n This is the single commit 'r1', if standalone.\n \n+While '{caret}' was about specifying a single commit parent, these\n+two notations consider all its parents. For example you can say\n+'HEAD{caret}2^@', however you cannot say 'HEAD{caret}@{caret}2'.\n+\n Revision Range Summary\n ----------------------\n \n-- \n2.9.0.windows.1\n\n"},{"id":"298820","messageId":"20160812070749.2920-11-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160812070749.2920-1-philipoakley@iee.org","subject":"[PATCH v5 10/12] doc: revisions - clarify reachability examples","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-12T07:07:47Z","receivedAt":"2016-08-12T07:09:36Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":" For the r1..r2 case, the exclusion of r1, rather than inclusion of r2,\n would be the unexpected case in natural language for a simple linear\n development, i.e. start..end excludes start.\n\nSigned-off-by: Philip Oakley \n---\nunchanged\n---\n Documentation/revisions.txt | 11 ++++++-----\n 1 file changed, 6 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 238be45..70864d5 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -254,7 +254,8 @@ Commit Exclusions\n '{caret}' (caret) Notation::\n To exclude commits reachable from a commit, a prefix '{caret}'\n notation is used. E.g. '{caret}r1 r2' means commits reachable\n- from 'r2' but exclude the ones reachable from 'r1'.\n+ from 'r2' but exclude the ones reachable from 'r1' (i.e. 'r1' and\n+ its ancestors).\n \n Dotted Range Notations\n ~~~~~~~~~~~~~~~~~~~~~~\n@@ -298,12 +299,12 @@ Revision Range Summary\n ----------------------\n \n ''::\n-\tInclude commits that are reachable from (i.e. ancestors of)\n-\t.\n+\tInclude commits that are reachable from (i.e. and its\n+\tancestors).\n \n '{caret}'::\n-\tExclude commits that are reachable from (i.e. ancestors of)\n-\t.\n+\tExclude commits that are reachable from (i.e. and its\n+\tancestors).\n \n '..'::\n \tInclude commits that are reachable from but exclude\n-- \n2.9.0.windows.1\n\n"},{"id":"298821","messageId":"20160812070749.2920-6-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160812070749.2920-1-philipoakley@iee.org","subject":"[PATCH v5 05/12] doc: revisions: extra clarification of ^! notation effects","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-12T07:07:42Z","receivedAt":"2016-08-12T07:10:01Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Signed-off-by: Philip Oakley \n---\nnew\nCc: Jakub Narębski \nhttps://public-inbox.org/git/578E4F4A.2020708%40gmail.com/\n---\n Documentation/revisions.txt | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 3da0083..0b5044d 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -281,7 +281,8 @@ for naming a set that is formed by a commit and its parent commits.\n \n The 'r1{caret}@' notation means all parents of 'r1'.\n \n-'r1{caret}!' includes commit 'r1' but excludes all of its parents.\n+'r1{caret}!' notation includes commit 'r1' but excludes all of its parents.\n+This is the single commit 'r1', if standalone.\n \n Revision Range Summary\n ----------------------\n-- \n2.9.0.windows.1\n\n"},{"id":"298822","messageId":"20160812070749.2920-4-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160812070749.2920-1-philipoakley@iee.org","subject":"[PATCH v5 03/12] doc: show the actual left, right, and boundary marks","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-12T07:07:40Z","receivedAt":"2016-08-12T07:10:04Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Signed-off-by: Philip Oakley \n---\nFound while checking the 'symmetric difference' documentation\nUnchanged from v4\n---\n Documentation/pretty-formats.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt\nindex 29b19b9..10719e1 100644\n--- a/Documentation/pretty-formats.txt\n+++ b/Documentation/pretty-formats.txt\n@@ -166,7 +166,7 @@ endif::git-rev-list[]\n respecting the `auto` settings of the former if we are going to a\n terminal). `auto` alone (i.e. `%C(auto)`) will turn on auto coloring\n on the next placeholders until the color is switched again.\n-- '%m': left, right or boundary mark\n+- '%m': left (`<`), right (`>`) or boundary (`-`) mark\n - '%n': newline\n - '%%': a raw '%'\n - '%x00': print a byte from a hex code\n-- \n2.9.0.windows.1\n\n"},{"id":"298823","messageId":"20160812070749.2920-2-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160812070749.2920-1-philipoakley@iee.org","subject":"[PATCH v5 01/12] doc: use 'symmetric difference' consistently","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-12T07:07:38Z","receivedAt":"2016-08-12T07:10:05Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Signed-off-by: Philip Oakley \n---\nunchanged\n---\n Documentation/gitk.txt | 2 +-\n Documentation/rev-list-options.txt | 4 ++--\n 2 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/gitk.txt b/Documentation/gitk.txt\nindex 6ade002..6c3eb15 100644\n--- a/Documentation/gitk.txt\n+++ b/Documentation/gitk.txt\n@@ -70,7 +70,7 @@ linkgit:git-rev-list[1] for a complete list.\n \n --left-right::\n \n-\tMark which side of a symmetric diff a commit is reachable\n+\tMark which side of a symmetric difference a commit is reachable\n \tfrom. Commits from the left side are prefixed with a `<`\n \tsymbol and those from the right with a `>` symbol.\n \ndiff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt\nindex 4f009d4..6dc0bb0 100644\n--- a/Documentation/rev-list-options.txt\n+++ b/Documentation/rev-list-options.txt\n@@ -225,7 +225,7 @@ excluded from the output.\n \n --left-only::\n --right-only::\n-\tList only commits on the respective side of a symmetric range,\n+\tList only commits on the respective side of a symmetric difference,\n \ti.e. only those which would be marked `<` resp. `>` by\n \t`--left-right`.\n +\n@@ -766,7 +766,7 @@ ifdef::git-rev-list[]\n endif::git-rev-list[]\n \n --left-right::\n-\tMark which side of a symmetric diff a commit is reachable from.\n+\tMark which side of a symmetric difference a commit is reachable from.\n \tCommits from the left side are prefixed with `<` and those from\n \tthe right with `>`. If combined with `--boundary`, those\n \tcommits are prefixed with `-`.\n-- \n2.9.0.windows.1\n\n"},{"id":"298824","messageId":"20160812070749.2920-8-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160812070749.2920-1-philipoakley@iee.org","subject":"[PATCH v5 07/12] doc: gitrevisions - use 'reachable' in page description","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-12T07:07:44Z","receivedAt":"2016-08-12T07:10:06Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Signed-off-by: Philip Oakley \n---\nunchanged\n---\n Documentation/gitrevisions.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/gitrevisions.txt b/Documentation/gitrevisions.txt\nindex e903eb7..33039c6 100644\n--- a/Documentation/gitrevisions.txt\n+++ b/Documentation/gitrevisions.txt\n@@ -15,8 +15,8 @@ DESCRIPTION\n \n Many Git commands take revision parameters as arguments. Depending on\n the command, they denote a specific commit or, for commands which\n-walk the revision graph (such as linkgit:git-log[1]), all commits which can\n-be reached from that commit. In the latter case one can also specify a\n+walk the revision graph (such as linkgit:git-log[1]), all commits which are\n+reachable from that commit. In the latter case one can also specify a\n range of revisions explicitly.\n \n In addition, some Git commands (such as linkgit:git-show[1]) also take\n-- \n2.9.0.windows.1\n\n"},{"id":"298825","messageId":"20160812070749.2920-5-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160812070749.2920-1-philipoakley@iee.org","subject":"[PATCH v5 04/12] doc: revisions: give headings for the two and three dot notations","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-12T07:07:41Z","receivedAt":"2016-08-12T07:10:08Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"While there, also break out the other shorthand notations and\nadd a title for the revision range summary (which also appears\nin git-rev-parse, so keep it mixed case).\n\nWe do not quote the notation within the headings as the asciidoc ->\ndocbook -> groff man viewer toolchain, particularly the docbook-groff\nstep, does not cope with two font changes, failing to return the heading\nfont to bold after the quotation of the notation.\n\nSigned-off-by: Philip Oakley \n---\nCc: Marc Branchaud \nCc: Jeff King \n\nref email\n\nJeff King wrote on 12 July 2016 23:12\n> On Tue, Jul 12, 2016 at 10:41:35PM +0100, Philip Oakley wrote:\n> > Marc Branchaud 12 July 2016 14:44 noted\n> > > +The '{caret}' (caret) notation\n> > > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n> > > To exclude commits reachable from a commit, a prefix '{caret}'\n> > > notation is used. E.g. '{caret}r1 r2' means commits reachable\n> > > from 'r2' but exclude the ones reachable from 'r1'.\n> >\n> > All of these headings render poorly in the manpage, at least for me\n> > (Ubuntu 16.04). Only the first word appears in bold; the '-quoted text\n> > is not bold but underlined, and the rest of the header is plain.\n>\n> Which doc package is that with? It had formatted OK for the html web pages.\n\nI get the same with:\n\n make gitrevisions.7\n man -l gitrevisions.7\n\nAsciidoc 8.6.9, docbook-xsl 4.5 if it matters.\n\nRendering single-quotes as underline is normal in this case (though it's\nnot great for punctuation like this, as it kind of blends with the dots;\nI know we use it elsewhere in this document, though). The failure to\ncontinue the bold through the end of line looks like a bug, though.\n\nThe generated XML (from asciidoc) looks reasonable:\n\n The <emphasis>..</emphasis> (two-dot) range notation\n\nThe roff looks like:\n\n .SS \"The \\fI\\&.\\&.\\fR (two\\-dot) range notation\"\n\nThe \"\\fR\" switches us back to \"Roman\" from italics, which is presumably\nthe problem. We really want to say \"switch back what we were using\nbefore \\fI\".\n\nSwitching it to \"\\fP\" fixes it, but it's not clear to me if that's\nactually portable, or a groff-ism. I don't know roff very well and\ndocumentation seems to be quite hard to find. So it's either a bug in\ndocbook, or an intentional decision they've made because roff can't\nportably do better. I'm not sure which.\n\n-Peff\n\nThe docbook folks have confirmed that \\fP would only work across one\nlevel, so they cannot use it for their XSLT conversion which must be\nmulti-level, so they always return to the default font.\n-Philip\n---\n Documentation/revisions.txt | 58 ++++++++++++++++++++++++++++-----------------\n 1 file changed, 36 insertions(+), 22 deletions(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 6e9cd41..3da0083 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -242,35 +242,49 @@ specifying a single revision with the notation described in the\n previous section means the set of commits reachable from that\n commit, following the commit ancestry chain.\n \n-To exclude commits reachable from a commit, a prefix '{caret}'\n-notation is used. E.g. '{caret}r1 r2' means commits reachable\n-from 'r2' but exclude the ones reachable from 'r1'.\n-\n-This set operation appears so often that there is a shorthand\n-for it. When you have two commits 'r1' and 'r2' (named according\n-to the syntax explained in SPECIFYING REVISIONS above), you can ask\n-for commits that are reachable from r2 excluding those that are reachable\n-from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.\n-\n-A similar notation 'r1\\...r2' is called symmetric difference\n-of 'r1' and 'r2' and is defined as\n-'r1 r2 --not $(git merge-base --all r1 r2)'.\n-It is the set of commits that are reachable from either one of\n-'r1' (left side) or 'r2' (right side) but not from both.\n-\n-In these two shorthands, you can omit one end and let it default to HEAD.\n+Commit Exclusions\n+~~~~~~~~~~~~~~~~~\n+\n+'{caret}' (caret) Notation::\n+ To exclude commits reachable from a commit, a prefix '{caret}'\n+ notation is used. E.g. '{caret}r1 r2' means commits reachable\n+ from 'r2' but exclude the ones reachable from 'r1'.\n+\n+Dotted Range Notations\n+~~~~~~~~~~~~~~~~~~~~~~\n+\n+The '..' (two-dot) Range Notation::\n+ The '{caret}r1 r2' set operation appears so often that there is a shorthand\n+ for it. When you have two commits 'r1' and 'r2' (named according\n+ to the syntax explained in SPECIFYING REVISIONS above), you can ask\n+ for commits that are reachable from r2 excluding those that are reachable\n+ from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.\n+\n+The '...' (three dot) Symmetric Difference Notation::\n+ A similar notation 'r1\\...r2' is called symmetric difference\n+ of 'r1' and 'r2' and is defined as\n+ 'r1 r2 --not $(git merge-base --all r1 r2)'.\n+ It is the set of commits that are reachable from either one of\n+ 'r1' (left side) or 'r2' (right side) but not from both.\n+\n+In these two shorthand notations, you can omit one end and let it default to HEAD.\n For example, 'origin..' is a shorthand for 'origin..HEAD' and asks \"What\n did I do since I forked from the origin branch?\" Similarly, '..origin'\n is a shorthand for 'HEAD..origin' and asks \"What did the origin do since\n I forked from them?\" Note that '..' would mean 'HEAD..HEAD' which is an\n empty range that is both reachable and unreachable from HEAD.\n \n-Two other shorthands for naming a set that is formed by a commit\n-and its parent commits exist. The 'r1{caret}@' notation means all\n-parents of 'r1'. 'r1{caret}!' includes commit 'r1' but excludes\n-all of its parents.\n+Other {caret} Parent Shorthand Notations\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+Two other shorthands exist, particularly useful for merge commits,\n+for naming a set that is formed by a commit and its parent commits.\n \n-To summarize:\n+The 'r1{caret}@' notation means all parents of 'r1'.\n+\n+'r1{caret}!' includes commit 'r1' but excludes all of its parents.\n+\n+Revision Range Summary\n+----------------------\n \n ''::\n \tInclude commits that are reachable from (i.e. ancestors of)\n-- \n2.9.0.windows.1\n\n"},{"id":"298826","messageId":"20160812070749.2920-1-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160720211007.5520-1-philipoakley@iee.org","subject":"[PATCH v5 00/12] Update git revisions","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-12T07:07:37Z","receivedAt":"2016-08-12T07:10:09Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"[2nd attempt : ISP troubles]\n\nThis has grown like topsy from a little two patch series that tried to\nname the 2-dots notation [1] into this extended set of tweaks.\n\nAs documentation can be rather personal, I've split out each small change\nso each can be individually justified.\n\nSince V4, I've confirmed that the format breaking issue is that we cannot\nquote code in headings in the man page layout - ultimately it's a docbook\ndecision, and follows the line of analysis Peff identified (see commentary\nin the patch).\n\nIn addition the multi-parent notations have been clarified and extended.\n\nThus the old patch 4 has been split into three. The first three patches are\nunchanged. The following 4 patches are also unchanged.\n\nFinally, at the end an extra 2 patches are added to build up the examples by\nincluding details of the notation expansions.\n\nThis updates po/range-doc (2016-07-20) 8 commits.\n\nHopefully my updated workflow will get the right patches to the right people.\n\n[1] https://public-inbox.org/git/0648000B273C412AB7140AE959EBC99A%40PhilipOakley/\n\nPhilip Oakley (12):\n doc: use 'symmetric difference' consistently\n doc: revisions - name the left and right sides\n doc: show the actual left, right, and boundary marks\n doc: revisions: give headings for the two and three dot notations\n doc: revisions: extra clarification of ^! notation effects\n doc: revisions: single vs multi-parent notation comparison\n doc: gitrevisions - use 'reachable' in page description\n doc: gitrevisions - clarify 'latter case' is revision walk\n doc: revisions - define `reachable`\n doc: revisions - clarify reachability examples\n doc: revisions: show revision expansion in examples\n doc: revisions: sort examples and fix alignment of the unchanged\n\n Documentation/gitk.txt | 2 +-\n Documentation/gitrevisions.txt | 6 +-\n Documentation/pretty-formats.txt | 2 +-\n Documentation/rev-list-options.txt | 4 +-\n Documentation/revisions.txt | 121 +++++++++++++++++++++++--------------\n 5 files changed, 84 insertions(+), 51 deletions(-)\n\n-- \n2.9.0.windows.1\n\n"},{"id":"298827","messageId":"20160812070749.2920-3-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160812070749.2920-1-philipoakley@iee.org","subject":"[PATCH v5 02/12] doc: revisions - name the left and right sides","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-12T07:07:39Z","receivedAt":"2016-08-12T07:10:10Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"The terms left and right side originate from the symmetric\ndifference. Name them there.\n\nSigned-off-by: Philip Oakley \n---\nunchanged\n---\n Documentation/revisions.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 19314e3..6e9cd41 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -256,7 +256,7 @@ A similar notation 'r1\\...r2' is called symmetric difference\n of 'r1' and 'r2' and is defined as\n 'r1 r2 --not $(git merge-base --all r1 r2)'.\n It is the set of commits that are reachable from either one of\n-'r1' or 'r2' but not from both.\n+'r1' (left side) or 'r2' (right side) but not from both.\n \n In these two shorthands, you can omit one end and let it default to HEAD.\n For example, 'origin..' is a shorthand for 'origin..HEAD' and asks \"What\n-- \n2.9.0.windows.1\n\n"},{"id":"298828","messageId":"20160812071026.gkpyxksl2kr3zhlv@sigill.intra.peff.net","threadId":"42687","inReplyTo":"20160812070749.2920-5-philipoakley@iee.org","subject":"Re: [PATCH v5 04/12] doc: revisions: give headings for the two and three dot notations","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2016-08-12T07:10:27Z","receivedAt":"2016-08-12T07:10:33Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Aug 12, 2016 at 08:07:41AM +0100, Philip Oakley wrote:\n\n> We do not quote the notation within the headings as the asciidoc ->\n> docbook -> groff man viewer toolchain, particularly the docbook-groff\n> step, does not cope with two font changes, failing to return the heading\n> font to bold after the quotation of the notation.\n> [...]\n> The docbook folks have confirmed that \\fP would only work across one\n> level, so they cannot use it for their XSLT conversion which must be\n> multi-level, so they always return to the default font.\n\nThanks for digging into the root cause. I think your workaround (to\navoid quoted bits in headers) is reasonable, and a rule we can keep in\nmind for future patches.\n\n-Peff\n"},{"id":"298837","messageId":"a5cae9c9-8d38-37ef-2924-6d3a397a1715@xiplink.com","threadId":"42687","inReplyTo":"20160812070749.2920-5-philipoakley@iee.org","subject":"Re: [PATCH v5 04/12] doc: revisions: give headings for the two and three dot notations","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2016-08-12T14:37:01Z","receivedAt":"2016-08-12T14:37:17Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"On 2016-08-12 03:07 AM, Philip Oakley wrote:\n> While there, also break out the other shorthand notations and\n> add a title for the revision range summary (which also appears\n> in git-rev-parse, so keep it mixed case).\n>\n> We do not quote the notation within the headings as the asciidoc ->\n> docbook -> groff man viewer toolchain, particularly the docbook-groff\n> step, does not cope with two font changes, failing to return the heading\n> font to bold after the quotation of the notation.\n\nLooks good --thanks!\n\n\t\tM.\n\n"},{"id":"298839","messageId":"c3271034-8fc5-3e29-ea1a-1c543abc7c52@xiplink.com","threadId":"42687","inReplyTo":"20160812070749.2920-6-philipoakley@iee.org","subject":"Re: [PATCH v5 05/12] doc: revisions: extra clarification of ^! notation effects","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2016-08-12T14:39:18Z","receivedAt":"2016-08-12T14:40:32Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"On 2016-08-12 03:07 AM, Philip Oakley wrote:\n> Signed-off-by: Philip Oakley \n> ---\n> new\n> Cc: Jakub Narębski \n> https://public-inbox.org/git/578E4F4A.2020708%40gmail.com/\n> ---\n> Documentation/revisions.txt | 3 ++-\n> 1 file changed, 2 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\n> index 3da0083..0b5044d 100644\n> --- a/Documentation/revisions.txt\n> +++ b/Documentation/revisions.txt\n> @@ -281,7 +281,8 @@ for naming a set that is formed by a commit and its parent commits.\n>\n> The 'r1{caret}@' notation means all parents of 'r1'.\n>\n> -'r1{caret}!' includes commit 'r1' but excludes all of its parents.\n> +'r1{caret}!' notation includes commit 'r1' but excludes all of its parents.\n\nThis sentence should start with \"The\".\n\n> +This is the single commit 'r1', if standalone.\n\nThat reads awkwardly to me. Perhaps\n\n\tBy itself, this notation denotes the single commit 'r1'.\n\n?\n\n\t\tM.\n\n"},{"id":"298840","messageId":"a3acb1fe-a1c2-cc66-315d-0dffb1291e8e@xiplink.com","threadId":"42687","inReplyTo":"20160812070749.2920-7-philipoakley@iee.org","subject":"Re: [PATCH v5 06/12] doc: revisions: single vs multi-parent notation comparison","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2016-08-12T14:40:59Z","receivedAt":"2016-08-12T14:41:33Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"On 2016-08-12 03:07 AM, Philip Oakley wrote:\n> Signed-off-by: Philip Oakley \n> ---\n> new\n> Junio's final comment https://public-inbox.org/git/xmqqwpkq6b4d.fsf%40gitster.mtv.corp.google.com/\n> ---\n> Documentation/revisions.txt | 4 ++++\n> 1 file changed, 4 insertions(+)\n>\n> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\n> index 0b5044d..934d071 100644\n> --- a/Documentation/revisions.txt\n> +++ b/Documentation/revisions.txt\n> @@ -284,6 +284,10 @@ The 'r1{caret}@' notation means all parents of 'r1'.\n> 'r1{caret}!' notation includes commit 'r1' but excludes all of its parents.\n> This is the single commit 'r1', if standalone.\n>\n> +While '{caret}' was about specifying a single commit parent, these\n> +two notations consider all its parents. For example you can say\n> +'HEAD{caret}2^@', however you cannot say 'HEAD{caret}@{caret}2'.\n\nThat ^ should be {caret}, right?\n\n\t\tM.\n\n"},{"id":"298841","messageId":"f418c41b-f590-0b6a-236a-c109a7296434@xiplink.com","threadId":"42687","inReplyTo":"20160812070749.2920-12-philipoakley@iee.org","subject":"Re: [PATCH v5 11/12] doc: revisions: show revision expansion in examples","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2016-08-12T15:22:26Z","receivedAt":"2016-08-12T15:22:31Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"On 2016-08-12 03:07 AM, Philip Oakley wrote:\n> The revisions examples show the revison arguments and the selected\n> commits, but do not show the intermediate step of the expansion of\n> the special 'range' notations. Extend the examples, including an\n> all-parents multi-parent merge commit example.\n>\n> Sort the examples and fix the alignment for those unaffected\n> in the next commit.\n>\n> Signed-off-by: Philip Oakley \n> ---\n> new\n> Cc: Jakub Narębski \n> ---\n> Documentation/revisions.txt | 19 +++++++++++++------\n> 1 file changed, 13 insertions(+), 6 deletions(-)\n>\n> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\n> index 70864d5..ac7dd8e 100644\n> --- a/Documentation/revisions.txt\n> +++ b/Documentation/revisions.txt\n> @@ -326,16 +326,23 @@ Revision Range Summary\n> as giving commit '' and then all its parents prefixed with\n> '{caret}' to exclude them (and their ancestors).\n>\n> -Here are a handful of examples:\n> +Here are a handful of examples using the Loeliger illustration above:\n>\n> + Args Expansion Selection\n\nI think \"Result\" would be better than \"Selection\" here.\n\nAlso, shouldn't all the ^ in these examples be {caret}? (I likely just \ndon't understand the rationale for using {caret} in some places and ^ in \nothers...)\n\n> D G H D\n> D F G H I J D F\n> ^G D H D\n> ^D B E I J F B\n> - B..C C\n> - B...C G H D E B C\n> + B..C = ^B C C\n> + B...C = B ^F C G H D E B C\n> ^D B C E I J F B C\n> C I J F C\n> - C^@ I J F\n> - C^! C\n> - F^! D G H D F\n> + C^@ = C^1\n\nI have a mixed reaction to showing this \"C^1\" expansion, and the \"B^1 \nB^2 B^3\" one as well. I see the appeal of showing the parent notation, \nbut really that was already explained to death in the first section. \nHere it's distracting. I think it's clearer for the reader to remove \nthese expansions and just use the node names from the illustration.\n\n> + = F I J F\n> + B^@ = B^1 B^2 B^3\n> + = D E F D G H E F I J\n> + C^! = C ^C^1\n\nI think this expansion might be better expressed as \"C ^C^@\". It'll be \nthe same for \"B^! = B ^B^@\" as well, which demonstrates a nice \nconsistency and also helps to emphasize the meaning of the ^@ notation.\n\n> + = C ^F C\n> + B^! = B ^B^1 ^B^2 ^B^3\n> + = B ^D ^E ^F B\n\nThe layout of these last two lines doesn't match the others. They \nshould be:\n\n B^! = B ^B^1 ^B^2 ^B^3\n = B ^D ^E ^F B\n\nI see that the next patch fixes the layout of the unchanged examples, \nbut it leaves these two unaligned.\n\n\t\tM.\n\n"},{"id":"298843","messageId":"58d0df88-4902-4519-df21-3ba3d86a19c9@xiplink.com","threadId":"42687","inReplyTo":"20160812070749.2920-1-philipoakley@iee.org","subject":"Re: [PATCH v5 00/12] Update git revisions","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2016-08-12T15:28:26Z","receivedAt":"2016-08-12T15:38:04Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"On 2016-08-12 03:07 AM, Philip Oakley wrote:\n> [2nd attempt : ISP troubles]\n>\n> This has grown like topsy from a little two patch series that tried to\n> name the 2-dots notation [1] into this extended set of tweaks.\n\nHonestly, I start just trying point out something concrete, like \nmisrendered headers, but then I figure since I'm sending a review \ncomment anyway I might as well go in-depth on the rest of the patch.\n\nI think I'm sticking to substantive comments, but if I'm getting too \npicky please just swat me down!\n\n\t\tM.\n\n"},{"id":"298883","messageId":"30B1A2CFFF9A4544A8F03800FA5968BD@PhilipOakley","threadId":"42687","inReplyTo":"58d0df88-4902-4519-df21-3ba3d86a19c9@xiplink.com","subject":"Re: [PATCH v5 00/12] Update git revisions","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-12T19:20:16Z","receivedAt":"2016-08-12T19:20:28Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Marc Branchaud\" \n> On 2016-08-12 03:07 AM, Philip Oakley wrote:\n>> [2nd attempt : ISP troubles]\n>>\n>> This has grown like topsy from a little two patch series that tried to\n>> name the 2-dots notation [1] into this extended set of tweaks.\n>\n> Honestly, I start just trying point out something concrete, like \n> misrendered headers, but then I figure since I'm sending a review comment \n> anyway I might as well go in-depth on the rest of the patch.\n>\n> I think I'm sticking to substantive comments, but if I'm getting too picky \n> please just swat me down!\n\nNo, that's fine. It's important to at least review these points.\n\nI thought I'd picked up all the issues, but it looks like I missed at least \none.\n\nThe caret thing has a bit of history - see 87c6aeb4efdd43559\n\nIt looks like its the two carets on a line mean superscript (Unconstrained \nquotes) and that maybe the issue.\n\nThen it looks like {caret} does a replacement, though I can't find that in \nthe asciidoc user guide.\n\n\nI don't quite understand why the ^ symbols work for the Loliger examples, \nbut hey ho, it's good they do...\n\nI'll work on the tweaks, though it'll probably be tomorrow as we have \nvisitors.\n\n--\nPhilip \n\n"},{"id":"298892","messageId":"xmqqoa4xvfsl.fsf@gitster.mtv.corp.google.com","threadId":"42687","inReplyTo":"30B1A2CFFF9A4544A8F03800FA5968BD@PhilipOakley","subject":"Re: [PATCH v5 00/12] Update git revisions","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-08-12T21:27:38Z","receivedAt":"2016-08-12T21:27:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" writes:\n\n> I'll work on the tweaks, though it'll probably be tomorrow as we have\n> visitors.\n\nThank you for working on this; Marc, thank you for many good review\ncomments.\n"},{"id":"298928","messageId":"38431C3FB1444813A222858D8F4D0390@PhilipOakley","threadId":"42687","inReplyTo":"c3271034-8fc5-3e29-ea1a-1c543abc7c52@xiplink.com","subject":"Re: [PATCH v5 05/12] doc: revisions: extra clarification of ^! notation effects","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-12T22:17:21Z","receivedAt":"2016-08-12T22:17:42Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Marc Branchaud\" \n> On 2016-08-12 03:07 AM, Philip Oakley wrote:\n>> Signed-off-by: Philip Oakley \n>> ---\n>> new\n>> Cc: Jakub Narębski \n>> https://public-inbox.org/git/578E4F4A.2020708%40gmail.com/\n>> ---\n>> Documentation/revisions.txt | 3 ++-\n>> 1 file changed, 2 insertions(+), 1 deletion(-)\n>>\n>> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\n>> index 3da0083..0b5044d 100644\n>> --- a/Documentation/revisions.txt\n>> +++ b/Documentation/revisions.txt\n>> @@ -281,7 +281,8 @@ for naming a set that is formed by a commit and its \n>> parent commits.\n>>\n>> The 'r1{caret}@' notation means all parents of 'r1'.\n>>\n>> -'r1{caret}!' includes commit 'r1' but excludes all of its parents.\n>> +'r1{caret}!' notation includes commit 'r1' but excludes all of its \n>> parents.\n>\n> This sentence should start with \"The\".\n\nAccepted. I'd simply split the the previous text, so the nice run-on effect \nit initially had has been lost.\n\n>\n>> +This is the single commit 'r1', if standalone.\n>\n> That reads awkwardly to me. Perhaps\n>\n> By itself, this notation denotes the single commit 'r1'.\n\nLike it. I'd toyed wth quite a few variants. It's jsut a case of finding the \nnicest one;-)\n\n>\n> ?\n>\n> M.\n>\n> --\n\nPhilip \n\n"},{"id":"298929","messageId":"75C139198D66446D8DEE561855DE8D4E@PhilipOakley","threadId":"42687","inReplyTo":"a3acb1fe-a1c2-cc66-315d-0dffb1291e8e@xiplink.com","subject":"Re: [PATCH v5 06/12] doc: revisions: single vs multi-parent notation comparison","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-12T22:23:28Z","receivedAt":"2016-08-12T22:23:35Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Marc Branchaud\" \n> On 2016-08-12 03:07 AM, Philip Oakley wrote:\n>> Signed-off-by: Philip Oakley \n>> ---\n>> new\n>> Junio's final comment \n>> https://public-inbox.org/git/xmqqwpkq6b4d.fsf%40gitster.mtv.corp.google.com/\n>> ---\n>> Documentation/revisions.txt | 4 ++++\n>> 1 file changed, 4 insertions(+)\n>>\n>> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\n>> index 0b5044d..934d071 100644\n>> --- a/Documentation/revisions.txt\n>> +++ b/Documentation/revisions.txt\n>> @@ -284,6 +284,10 @@ The 'r1{caret}@' notation means all parents of 'r1'.\n>> 'r1{caret}!' notation includes commit 'r1' but excludes all of its \n>> parents.\n>> This is the single commit 'r1', if standalone.\n>>\n>> +While '{caret}' was about specifying a single commit parent, \n>> these\n>> +two notations consider all its parents. For example you can say\n>> +'HEAD{caret}2^@', however you cannot say 'HEAD{caret}@{caret}2'.\n>\n> That ^ should be {caret}, right?\n>\nYes (I think so - will change).\n\nI had planned to change it but it looks like I missed it.\n\nIn an earlier version I hadn't changed any of them (or maybe just one) and \nthe asciidoc barfed. I suspect that the ^ ^ symbols have to be paired \nproperly, and a bad pairing around / across the quotes makes the parsing \nfail. it looks like singletons (which clearly never pair) are accespted 'as \nis'\n\nI think the later examples are inside some form of a block quote with no \nexpansions at all.\n\n--\nPhilip\n\n\n> M.\n>\n> \n\n"},{"id":"298934","messageId":"7765A995ADF6470DBA99D000AF7B5538@PhilipOakley","threadId":"42687","inReplyTo":"f418c41b-f590-0b6a-236a-c109a7296434@xiplink.com","subject":"Re: [PATCH v5 11/12] doc: revisions: show revision expansion in examples","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-12T22:45:05Z","receivedAt":"2016-08-12T22:46:24Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Marc Branchaud\" \n> On 2016-08-12 03:07 AM, Philip Oakley wrote:\n>> The revisions examples show the revison arguments and the selected\n>> commits, but do not show the intermediate step of the expansion of\n>> the special 'range' notations. Extend the examples, including an\n>> all-parents multi-parent merge commit example.\n>>\n>> Sort the examples and fix the alignment for those unaffected\n>> in the next commit.\n>>\n>> Signed-off-by: Philip Oakley \n>> ---\n>> new\n>> Cc: Jakub Narębski \n>> ---\n>> Documentation/revisions.txt | 19 +++++++++++++------\n>> 1 file changed, 13 insertions(+), 6 deletions(-)\n>>\n>> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\n>> index 70864d5..ac7dd8e 100644\n>> --- a/Documentation/revisions.txt\n>> +++ b/Documentation/revisions.txt\n>> @@ -326,16 +326,23 @@ Revision Range Summary\n>> as giving commit '' and then all its parents prefixed with\n>> '{caret}' to exclude them (and their ancestors).\n>>\n>> -Here are a handful of examples:\n>> +Here are a handful of examples using the Loeliger illustration above:\n>>\n>> + Args Expansion Selection\n>\n> I think \"Result\" would be better than \"Selection\" here.\n\nI wanted to avoid that. I feel that \"Result\" is too general. I had thought \nabout using the 'ed' rather than 'ion' word endings, but that would require \n(to my mind) the noun e.g. \"Expanded arguments\" and \" Selected commits\" \n(still could be - see below), while the 'ion' endings felt complete. The \nResult is what is shown in thable below these headings ;-)\n\n\n>\n> Also, shouldn't all the ^ in these examples be {caret}? (I likely just \n> don't understand the rationale for using {caret} in some places and ^ in \n> others...)\n\nAll the conversions appear to work. I think that asciidoc is viewing these a \nblocked text without any expansion. Plus, it would be horrendous trying to \ncheck the formatting (endless reruns of make.. ... .. )\n\n>\n>> D G H D\n>> D F G H I J D F\n>> ^G D H D\n>> ^D B E I J F B\n>> - B..C C\n>> - B...C G H D E B C\n>> + B..C = ^B C C\n>> + B...C = B ^F C G H D E B C\n>> ^D B C E I J F B C\n>> C I J F C\n>> - C^@ I J F\n>> - C^! C\n>> - F^! D G H D F\n>> + C^@ = C^1\n>\n> I have a mixed reaction to showing this \"C^1\" expansion, and the \"B^1 B^2 \n> B^3\" one as well. I see the appeal of showing the parent notation, but \n> really that was already explained to death in the first section.\n\nThis was the whole point. For some (e.g. me) the explanations had fallen \nflat on their face, and it was difficult to see what it was on about. Now I \nknow, it's all obvious, but what was needed was a carefully stepped through \nexample or two. If the dear reader can't see the big steps, let's give them \nsmall steps.\n\nJacob had given an 'example' in response to my early query, but it just felt \nlike repetion of what had already been said, but it didn't take the next \n[small] step, which this example does (partly because it can as it can use \nthe Loeliger diagram, which wasn't available in Jacob's example).\n\nI also deliberately added the B^@ and B^! (standalone) example as the C^@ \nand C^! didn't have an 'all parents' (plurals!), but it did have the \nindentation issue - see above about stretching out the headers, which would \ngive more space for the indentations.\n\n> Here it's distracting. I think it's clearer for the reader to remove \n> these expansions and just use the node names from the illustration.\n>\n>> + = F I J F\n>> + B^@ = B^1 B^2 B^3\n>> + = D E F D G H E F I J\n>> + C^! = C ^C^1\n>\n> I think this expansion might be better expressed as \"C ^C^@\".\n\nI hadn't viewed it that way. It would be an extra step.\n\n> It'll be the same for \"B^! = B ^B^@\" as well, which demonstrates a \n> nice consistency and also helps to emphasize the meaning of the ^@ \n> notation.\n>\n>> + = C ^F C\n>> + B^! = B ^B^1 ^B^2 ^B^3\n>> + = B ^D ^E ^F B\n>\n> The layout of these last two lines doesn't match the others. They should \n> be:\n>\n> B^! = B ^B^1 ^B^2 ^B^3\n> = B ^D ^E ^F B\n>\n> I see that the next patch fixes the layout of the unchanged examples, but \n> it leaves these two unaligned.\n\nAs noted it was about squeezing that one in. I'll look at alternate heading \ntitles and spacing options.\n\n\n--\nPhilip \n\n"},{"id":"298937","messageId":"20160812234522.7792-1-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160811215035.4108-1-philipoakley@iee.org","subject":"[PATCH v6 00/12] Update git revisions","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-12T23:45:18Z","receivedAt":"2016-08-12T23:45:43Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"These are the quick fixes to Marc's comments to patches 5,6,11,\nand a consequential change to 12.\n\nOnly the changed patches are included.\n\nPhilip Oakley (12):\n doc: use 'symmetric difference' consistently\n doc: revisions - name the left and right sides\n doc: show the actual left, right, and boundary marks\n doc: revisions: give headings for the two and three dot notations\n doc: revisions: extra clarification of ^! notation effects\n doc: revisions: single vs multi-parent notation comparison\n doc: gitrevisions - use 'reachable' in page description\n doc: gitrevisions - clarify 'latter case' is revision walk\n doc: revisions - define `reachable`\n doc: revisions - clarify reachability examples\n doc: revisions: show revision expansion in examples\n doc: revisions: sort examples and fix alignment of the unchanged\n\n Documentation/gitk.txt | 2 +-\n Documentation/gitrevisions.txt | 6 +-\n Documentation/pretty-formats.txt | 2 +-\n Documentation/rev-list-options.txt | 4 +-\n Documentation/revisions.txt | 125 ++++++++++++++++++++++++-------------\n 5 files changed, 88 insertions(+), 51 deletions(-)\n\n-- \n2.9.0.windows.1\n\n"},{"id":"298938","messageId":"20160812234522.7792-3-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160812234522.7792-1-philipoakley@iee.org","subject":"[PATCH v6 06/12] doc: revisions: single vs multi-parent notation comparison","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-12T23:45:20Z","receivedAt":"2016-08-12T23:45:47Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Signed-off-by: Philip Oakley \n---\nv6 updated\nJunio's final comment https://public-inbox.org/git/xmqqwpkq6b4d.fsf%40gitster.mtv.corp.google.com/\nCc: Marc Branchaud \n---\n Documentation/revisions.txt | 4 ++++\n 1 file changed, 4 insertions(+)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 17fc45c..242123b 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -284,6 +284,10 @@ The 'r1{caret}@' notation means all parents of 'r1'.\n The 'r1{caret}!' notation includes commit 'r1' but excludes all of its parents.\n By itself, this notation denotes the single commit 'r1'.\n \n+While '{caret}' was about specifying a single commit parent, these\n+two notations consider all its parents. For example you can say\n+'HEAD{caret}2{caret}@', however you cannot say 'HEAD{caret}@{caret}2'.\n+\n Revision Range Summary\n ----------------------\n \n-- \n2.9.0.windows.1\n\n"},{"id":"298939","messageId":"20160812234522.7792-5-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160812234522.7792-1-philipoakley@iee.org","subject":"[PATCH v6 12/12] doc: revisions: sort examples and fix alignment of the unchanged","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-12T23:45:22Z","receivedAt":"2016-08-12T23:45:48Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"The previous commit adjusted the column alignment for revision\nexamples which show expansion. Fix the unchanged examples and sort\nthose that show expansions to the end of the list.\n\nSigned-off-by: Philip Oakley \n---\nv6 updated\nCc: Marc Branchaud \n---\n Documentation/revisions.txt | 12 ++++++------\n 1 file changed, 6 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex f15d5ed..b9b45c0 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -331,14 +331,14 @@ with each step in the notation's expansion and selection carefully\n spelt out:\n \n Args Expanded arguments Selected commits\n- D G H D\n- D F G H I J D F\n- ^G D H D\n- ^D B E I J F B\n+ D G H D\n+ D F G H I J D F\n+ ^G D H D\n+ ^D B E I J F B\n+ ^D B C E I J F B C\n+ C I J F C\n B..C = ^B C C\n B...C = B ^F C G H D E B C\n- ^D B C E I J F B C\n- C I J F C\n C^@ = C^1\n = F I J F\n B^@ = B^1 B^2 B^3\n-- \n2.9.0.windows.1\n\n"},{"id":"298940","messageId":"20160812234522.7792-4-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160812234522.7792-1-philipoakley@iee.org","subject":"[PATCH v6 11/12] doc: revisions: show revision expansion in examples","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-12T23:45:21Z","receivedAt":"2016-08-12T23:45:49Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"The revisions examples show the revison arguments and the selected\ncommits, but do not show the intermediate step of the expansion of\nthe special 'range' notations. Extend the examples, including an\nall-parents multi-parent merge commit example.\n\nSort the examples and fix the alignment for those unaffected\nin the next commit.\n\nSigned-off-by: Philip Oakley \n---\nv6 updated\nCc: Jakub Narębski \nCc: Marc Branchaud \n---\n Documentation/revisions.txt | 23 +++++++++++++++++------\n 1 file changed, 17 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex e9a74fc..f15d5ed 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -326,16 +326,27 @@ Revision Range Summary\n as giving commit '' and then all its parents prefixed with\n '{caret}' to exclude them (and their ancestors).\n \n-Here are a handful of examples:\n+Here are a handful of examples using the Loeliger illustration above,\n+with each step in the notation's expansion and selection carefully\n+spelt out:\n \n+ Args Expanded arguments Selected commits\n D G H D\n D F G H I J D F\n ^G D H D\n ^D B E I J F B\n- B..C C\n- B...C G H D E B C\n+ B..C = ^B C C\n+ B...C = B ^F C G H D E B C\n ^D B C E I J F B C\n C I J F C\n- C^@ I J F\n- C^! C\n- F^! D G H D F\n+ C^@ = C^1\n+ = F I J F\n+ B^@ = B^1 B^2 B^3\n+ = D E F D G H E F I J\n+ C^! = C ^C^@\n+ = C ^C^1\n+ = C ^F C\n+ B^! = B ^B^@\n+ = B ^B^1 ^B^2 ^B^3\n+ = B ^D ^E ^F B\n+ F^! D = F ^I ^J D G H D F\n-- \n2.9.0.windows.1\n\n"},{"id":"298941","messageId":"20160812234522.7792-2-philipoakley@iee.org","threadId":"42687","inReplyTo":"20160812234522.7792-1-philipoakley@iee.org","subject":"[PATCH v6 05/12] doc: revisions: extra clarification of ^! notation effects","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-12T23:45:19Z","receivedAt":"2016-08-12T23:45:51Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Signed-off-by: Philip Oakley \n---\nv6 updated\nCc: Jakub Narębski \nCc: Marc Branchaud \nhttps://public-inbox.org/git/578E4F4A.2020708%40gmail.com/\n---\n Documentation/revisions.txt | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 3da0083..17fc45c 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -281,7 +281,8 @@ for naming a set that is formed by a commit and its parent commits.\n \n The 'r1{caret}@' notation means all parents of 'r1'.\n \n-'r1{caret}!' includes commit 'r1' but excludes all of its parents.\n+The 'r1{caret}!' notation includes commit 'r1' but excludes all of its parents.\n+By itself, this notation denotes the single commit 'r1'.\n \n Revision Range Summary\n ----------------------\n-- \n2.9.0.windows.1\n\n"},{"id":"299347","messageId":"5338959f-985f-d1b3-7287-eccde559d2c3@xiplink.com","threadId":"42687","inReplyTo":"20160812234522.7792-1-philipoakley@iee.org","subject":"Re: [PATCH v6 00/12] Update git revisions","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2016-08-15T14:30:20Z","receivedAt":"2016-08-15T14:30:27Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"On 2016-08-12 07:45 PM, Philip Oakley wrote:\n> These are the quick fixes to Marc's comments to patches 5,6,11,\n> and a consequential change to 12.\n>\n> Only the changed patches are included.\n\nLooks good to me -- no further comments!\n\nHowever, I still don't understand why git says 11/12 has \"indent with \nspaces\" problems.\n\n\t\tM.\n\n\n> Philip Oakley (12):\n> doc: use 'symmetric difference' consistently\n> doc: revisions - name the left and right sides\n> doc: show the actual left, right, and boundary marks\n> doc: revisions: give headings for the two and three dot notations\n> doc: revisions: extra clarification of ^! notation effects\n> doc: revisions: single vs multi-parent notation comparison\n> doc: gitrevisions - use 'reachable' in page description\n> doc: gitrevisions - clarify 'latter case' is revision walk\n> doc: revisions - define `reachable`\n> doc: revisions - clarify reachability examples\n> doc: revisions: show revision expansion in examples\n> doc: revisions: sort examples and fix alignment of the unchanged\n>\n> Documentation/gitk.txt | 2 +-\n> Documentation/gitrevisions.txt | 6 +-\n> Documentation/pretty-formats.txt | 2 +-\n> Documentation/rev-list-options.txt | 4 +-\n> Documentation/revisions.txt | 125 ++++++++++++++++++++++++-------------\n> 5 files changed, 88 insertions(+), 51 deletions(-)\n>\n"},{"id":"299348","messageId":"8191B8FB581F44AAA7E2467A845C7532@PhilipOakley","threadId":"42687","inReplyTo":"5338959f-985f-d1b3-7287-eccde559d2c3@xiplink.com","subject":"Re: [PATCH v6 00/12] Update git revisions","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-15T15:00:03Z","receivedAt":"2016-08-15T15:00:11Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Marc Branchaud\" \n> On 2016-08-12 07:45 PM, Philip Oakley wrote:\n>> These are the quick fixes to Marc's comments to patches 5,6,11,\n>> and a consequential change to 12.\n>>\n>> Only the changed patches are included.\n>\n> Looks good to me -- no further comments!\n>\n> However, I still don't understand why git says 11/12 has \"indent with \n> spaces\" problems.\n\nI'm guessing it's that the text is monospaced rather than tabbed, and it's \nflagging that.\n\nI'd noticed that it was highlighted in the Git gui (which I use to visualise \nboth the diff, the message and the part after the three dashes at the same \ntime).\n\n\n>\n> M.\n>\n>\n>> Philip Oakley (12):\n>> doc: use 'symmetric difference' consistently\n>> doc: revisions - name the left and right sides\n>> doc: show the actual left, right, and boundary marks\n>> doc: revisions: give headings for the two and three dot notations\n>> doc: revisions: extra clarification of ^! notation effects\n>> doc: revisions: single vs multi-parent notation comparison\n>> doc: gitrevisions - use 'reachable' in page description\n>> doc: gitrevisions - clarify 'latter case' is revision walk\n>> doc: revisions - define `reachable`\n>> doc: revisions - clarify reachability examples\n>> doc: revisions: show revision expansion in examples\n>> doc: revisions: sort examples and fix alignment of the unchanged\n>>\n>> Documentation/gitk.txt | 2 +-\n>> Documentation/gitrevisions.txt | 6 +-\n>> Documentation/pretty-formats.txt | 2 +-\n>> Documentation/rev-list-options.txt | 4 +-\n>> Documentation/revisions.txt | 125 \n>> ++++++++++++++++++++++++-------------\n>> 5 files changed, 88 insertions(+), 51 deletions(-)\n\n"},{"id":"299358","messageId":"5eda6874-43c8-7383-bbb3-b482a388370d@xiplink.com","threadId":"42687","inReplyTo":"8191B8FB581F44AAA7E2467A845C7532@PhilipOakley","subject":"BUG: indent-with-non-tab always on (was: Re: [PATCH v6 00/12] Update git revisions)","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2016-08-15T16:55:47Z","receivedAt":"2016-08-15T16:55:52Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"On 2016-08-15 11:00 AM, Philip Oakley wrote:\n> From: \"Marc Branchaud\" \n>> On 2016-08-12 07:45 PM, Philip Oakley wrote:\n>>> These are the quick fixes to Marc's comments to patches 5,6,11,\n>>> and a consequential change to 12.\n>>>\n>>> Only the changed patches are included.\n>>\n>> Looks good to me -- no further comments!\n>>\n>> However, I still don't understand why git says 11/12 has \"indent with\n>> spaces\" problems.\n>\n> I'm guessing it's that the text is monospaced rather than tabbed, and\n> it's flagging that.\n>\n> I'd noticed that it was highlighted in the Git gui (which I use to\n> visualise both the diff, the message and the part after the three dashes\n> at the same time).\n\nActually, it looks like an indent-with-non-tab problem, which is \nsupposed to be off by default.\n\nGit doesn't complain about the patch if I set\n\tcore.whitespace = tabwidth=11\npresumably because the patch uses 10 spaces to indent the offending lines.\n\nBut explicitly disabling that check with\n\tcore.whitespace = -indent-with-non-tab\ndoesn't work.\n\nUnfortunately, I don't have time today to track this down.\n\n\t\tM.\n\n"},{"id":"299360","messageId":"xmqqzioegdx4.fsf@gitster.mtv.corp.google.com","threadId":"42687","inReplyTo":"5338959f-985f-d1b3-7287-eccde559d2c3@xiplink.com","subject":"Re: [PATCH v6 00/12] Update git revisions","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-08-15T17:06:15Z","receivedAt":"2016-08-15T17:06:23Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Marc Branchaud writes:\n\n> On 2016-08-12 07:45 PM, Philip Oakley wrote:\n>> These are the quick fixes to Marc's comments to patches 5,6,11,\n>> and a consequential change to 12.\n>>\n>> Only the changed patches are included.\n>\n> Looks good to me -- no further comments!\n>\n> However, I still don't understand why git says 11/12 has \"indent with\n> spaces\" problems.\n\nProbably that is because Documentation/.gitattributes has\n\n\t*.txt whitespace\n\nto tell Git to notice all types of potential whitespace errors known\nto it. The checking of indent-with-tab is deliberate here, because\nwe rely on the fact that asciidoc treats HT as \"fill with necessary\nspaces to next multiple of 8\" even when it renders a fixed-column\ndrawing.\n"},{"id":"299363","messageId":"114095ef-e267-c9bb-c5fc-52bdb5598fe6@xiplink.com","threadId":"42687","inReplyTo":"5eda6874-43c8-7383-bbb3-b482a388370d@xiplink.com","subject":"Re: BUG: indent-with-non-tab always on","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2016-08-15T17:54:01Z","receivedAt":"2016-08-15T17:54:19Z","isPatch":false,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"On 2016-08-15 12:55 PM, Marc Branchaud wrote:\n> On 2016-08-15 11:00 AM, Philip Oakley wrote:\n>> From: \"Marc Branchaud\" \n>>> On 2016-08-12 07:45 PM, Philip Oakley wrote:\n>>>> These are the quick fixes to Marc's comments to patches 5,6,11,\n>>>> and a consequential change to 12.\n>>>>\n>>>> Only the changed patches are included.\n>>>\n>>> Looks good to me -- no further comments!\n>>>\n>>> However, I still don't understand why git says 11/12 has \"indent with\n>>> spaces\" problems.\n>>\n>> I'm guessing it's that the text is monospaced rather than tabbed, and\n>> it's flagging that.\n>>\n>> I'd noticed that it was highlighted in the Git gui (which I use to\n>> visualise both the diff, the message and the part after the three dashes\n>> at the same time).\n>\n> Actually, it looks like an indent-with-non-tab problem, which is\n> supposed to be off by default.\n>\n> Git doesn't complain about the patch if I set\n> core.whitespace = tabwidth=11\n> presumably because the patch uses 10 spaces to indent the offending lines.\n>\n> But explicitly disabling that check with\n> core.whitespace = -indent-with-non-tab\n> doesn't work.\n>\n> Unfortunately, I don't have time today to track this down.\n\nGah, never mind -- didn't realize it was turned on in \nDocumentation/.gitattributes.\n\n\t\tM.\n\n"},{"id":"300233","messageId":"eca8d854-9483-ea30-c5a8-71a35c3ca7bd@gmail.com","threadId":"42687","inReplyTo":"20160811215035.4108-2-philipoakley@iee.org","subject":"Re: [PATCH v5 01/12] doc: use 'symmetric difference' consistently","fromName":"Jakub Narębski","fromEmail":"jnareb@gmail.com","sentAt":"2016-08-26T11:33:08Z","receivedAt":"2016-08-26T11:34:08Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"W dniu 11.08.2016 o 23:50, Philip Oakley pisze:\n \n> diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt\n> index 4f009d4..6dc0bb0 100644\n> --- a/Documentation/rev-list-options.txt\n> +++ b/Documentation/rev-list-options.txt\n> @@ -225,7 +225,7 @@ excluded from the output.\n> \n> --left-only::\n> --right-only::\n> -\tList only commits on the respective side of a symmetric range,\n> +\tList only commits on the respective side of a symmetric difference,\n> \ti.e. only those which would be marked `<` resp. `>` by\n> \t`--left-right`.\n> +\n> @@ -766,7 +766,7 @@ ifdef::git-rev-list[]\n> endif::git-rev-list[]\n> \n> --left-right::\n> -\tMark which side of a symmetric diff a commit is reachable from.\n> +\tMark which side of a symmetric difference a commit is reachable from.\n> \tCommits from the left side are prefixed with `<` and those from\n> \tthe right with `>`. If combined with `--boundary`, those\n> \tcommits are prefixed with `-`.\n\nThat's very nice that two^W three related options, namely --left-only,\n--right-only and --left-right now use the same notation.\n\nI guess that \"symmetric range\" was to mean \"symmetric difference range\".\n\nBest,\n-- \nJakub Narębski\n\n"},{"id":"300259","messageId":"6b37851f-0f2f-0379-c10e-52f7da6b7110@gmail.com","threadId":"42687","inReplyTo":"20160812234522.7792-3-philipoakley@iee.org","subject":"Re: [PATCH v6 06/12] doc: revisions: single vs multi-parent notation comparison","fromName":"Jakub Narębski","fromEmail":"jnareb@gmail.com","sentAt":"2016-08-26T15:30:59Z","receivedAt":"2016-08-26T15:31:11Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"W dniu 13.08.2016 o 01:45, Philip Oakley pisze:\n\n> --- a/Documentation/revisions.txt\n> +++ b/Documentation/revisions.txt\n> @@ -284,6 +284,10 @@ The 'r1{caret}@' notation means all parents of 'r1'.\n> The 'r1{caret}!' notation includes commit 'r1' but excludes all of its parents.\n> By itself, this notation denotes the single commit 'r1'.\n> \n> +While '{caret}' was about specifying a single commit parent, these\n> +two notations consider all its parents. For example you can say\n> +'HEAD{caret}2{caret}@', however you cannot say 'HEAD{caret}@{caret}2'.\n> +\n\nThat's good to have.\n\nThough I do wonder if it is implementation limitation, or if it is something\ninherent in the notation, namely that ^@ and ^! resolve (the former\nat least in general, though not for every ) to more than one revision\nspecifier.\n\nAnyway, good addition!\n-- \nJakub Narębski\n\n"},{"id":"300261","messageId":"xmqq60qnjyuo.fsf@gitster.mtv.corp.google.com","threadId":"42687","inReplyTo":"eca8d854-9483-ea30-c5a8-71a35c3ca7bd@gmail.com","subject":"Re: [PATCH v5 01/12] doc: use 'symmetric difference' consistently","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-08-26T16:09:51Z","receivedAt":"2016-08-26T16:15:10Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jakub Narębski writes:\n\n>> --left-right::\n>> -\tMark which side of a symmetric diff a commit is reachable from.\n>> +\tMark which side of a symmetric difference a commit is reachable from.\n>> \tCommits from the left side are prefixed with `<` and those from\n>> \tthe right with `>`. If combined with `--boundary`, those\n>> \tcommits are prefixed with `-`.\n>\n> That's very nice that two^W three related options, namely --left-only,\n> --right-only and --left-right now use the same notation.\n>\n> I guess that \"symmetric range\" was to mean \"symmetric difference range\".\n\nBy \"symmetric difference\", we mean a \"set difference\" operation that\nis symmetric. Contrasting with asymmetric difference that gives a\nset of elements that belong to set A but do not belong to set B\n(i.e. B..A), symmetric difference of set A and set B gives a set of\nelements that belong to either set A alone or set B alone but not\nboth (i.e. A...B).\n\nSo if you really want a fully spelled name, we would not want to\ncall it with a name with \"range\". It is \"symmetric set difference\",\nand \"symmetric difference\" in the updated sentence is a short-hand\nfor that.\n"},{"id":"300262","messageId":"xmqqwpj3ijtd.fsf@gitster.mtv.corp.google.com","threadId":"42687","inReplyTo":"6b37851f-0f2f-0379-c10e-52f7da6b7110@gmail.com","subject":"Re: [PATCH v6 06/12] doc: revisions: single vs multi-parent notation comparison","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-08-26T16:19:58Z","receivedAt":"2016-08-26T16:20:08Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jakub Narębski writes:\n\n> W dniu 13.08.2016 o 01:45, Philip Oakley pisze:\n>\n>> +'HEAD{caret}2{caret}@', however you cannot say 'HEAD{caret}@{caret}2'.\n>\n> Though I do wonder if it is implementation limitation, or if it is something\n> inherent in the notation, namely that ^@ and ^! resolve (the former\n> at least in general, though not for every ) to more than one revision\n> specifier.\n\nI think that the answer you are giving to the question is the latter,\nand I tend to agree with you.\n\nYou could define: A^@ followed by means first expand A^@,\nand then apply that to each and every one in the resulting\nset. But some may be merges and while others not. It is unclear\nwhat should happen to A^@^2 when one of A's parents has only one\nparent. In some use cases, it would be convenient if parents of A\nto which the operation cannot be applied, but in other\nuse cases, it would be convenient if the whole thing caused an error.\nThe notation is not detailed/rich enough to express the distinction.\n\n\n"},{"id":"300369","messageId":"494c1bd2-19c8-e2af-da1c-ff1331f91c4f@gmail.com","threadId":"42687","inReplyTo":"20160812070749.2920-10-philipoakley@iee.org","subject":"Re: [PATCH v5 09/12] doc: revisions - define `reachable`","fromName":"Jakub Narębski","fromEmail":"jnareb@gmail.com","sentAt":"2016-08-28T13:01:46Z","receivedAt":"2016-08-28T13:02:16Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"W dniu 12.08.2016 o 09:07, Philip Oakley pisze:\n[...]\n\n> History traversing commands such as `git log` operate on a set\n> -of commits, not just a single commit. To these commands,\n> -specifying a single revision with the notation described in the\n> -previous section means the set of commits reachable from that\n> -commit, following the commit ancestry chain.\n> +of commits, not just a single commit.\n> +\n> +For these commands,\n> +specifying a single revision, using the notation described in the\n> +previous section, means the set of commits `reachable` from the given\n> +commit.\n\nWhy such strange formatting? Is it to keep original contents\nfor better blame / word diff?\n\n> +\n> +A commit's reachable set is the commit itself and the commits in\n> +its ancestry chain.\n> +\n\nIt is all right, but perhaps it would be better to just repeat:\n\n +Set of commits reachable from given commit is the commit itself\n +and all the commits in its ancestry chain.\n\n-- \nJakub Narębski\n\n"},{"id":"300458","messageId":"EDA7BA88AB1D42C7B4228D71CC28145B@PhilipOakley","threadId":"42687","inReplyTo":"494c1bd2-19c8-e2af-da1c-ff1331f91c4f@gmail.com","subject":"Re: [PATCH v5 09/12] doc: revisions - define `reachable`","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-29T13:21:14Z","receivedAt":"2016-08-29T13:21:26Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Jakub Narębski\" \nSent: Sunday, August 28, 2016 2:01 PM\n>W dniu 12.08.2016 o 09:07, Philip Oakley pisze:\n> [...]\n>\n>> History traversing commands such as `git log` operate on a set\n>> -of commits, not just a single commit. To these commands,\n>> -specifying a single revision with the notation described in the\n>> -previous section means the set of commits reachable from that\n>> -commit, following the commit ancestry chain.\n>> +of commits, not just a single commit.\n>> +\n>> +For these commands,\n>> +specifying a single revision, using the notation described in the\n>> +previous section, means the set of commits `reachable` from the given\n>> +commit.\n>\n> Why such strange formatting? Is it to keep original contents\n> for better blame / word diff?\n\nStrange as in 'not reflowed'? - yes that was the reason. It can be hard to \nsee the wood from the trees if there is a lot of reflow going on, as it can \nhide the issue behind the key change.\n\nI did slightly abuse notation by quoting `reachable` to indicate that it's a \nterm with a precise definition that can be confusing to those that don't \nknow. I also split out the reachability parts into their own paragraphs.\n\n>\n>> +\n>> +A commit's reachable set is the commit itself and the commits in\n>> +its ancestry chain.\n>> +\n>\n> It is all right, but perhaps it would be better to just repeat:\n>\n> +Set of commits reachable from given commit is the commit itself\n> +and all the commits in its ancestry chain.\n\nIt's very easy to go around in circles here. The original issue was the A..B \nnotation for the case where A is a direct descendant of B, such that new \nusers, or users more familiar with range notations from elsewhere, would \nexpect that the A..B range is *inclusive*, rather than an open / closed \ninterval. It was the addressing of that problem that lead to the updating of \nthe 'reachability' definition.\n\nThe main part of my sentence formation was to make the 'reachable' part the \ndefining element, rather than being a feature of the set. Maybe it's using \nthe 'set' viewpoint that is distracting?\n>\n> -- \n> Jakub Narębski\n>\n> \n\n"},{"id":"300461","messageId":"557eb782-ee45-3e33-33bb-aa88817dcd82@gmail.com","threadId":"42687","inReplyTo":"EDA7BA88AB1D42C7B4228D71CC28145B@PhilipOakley","subject":"Re: [PATCH v5 09/12] doc: revisions - define `reachable`","fromName":"Jakub Narębski","fromEmail":"jnareb@gmail.com","sentAt":"2016-08-29T14:43:32Z","receivedAt":"2016-08-29T14:43:50Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"W dniu 29.08.2016 o 15:21, Philip Oakley pisze:\n> From: \"Jakub Narębski\" \n> Sent: Sunday, August 28, 2016 2:01 PM\n>> W dniu 12.08.2016 o 09:07, Philip Oakley pisze:\n[...]\n\n>>> +For these commands,\n>>> +specifying a single revision, using the notation described in the\n>>> +previous section, means the set of commits `reachable` from the given\n>>> +commit.\n[...]\n>>> +\n>>> +A commit's reachable set is the commit itself and the commits in\n>>> +its ancestry chain.\n>>> +\n>>\n>> It is all right, but perhaps it would be better to just repeat:\n>>\n>> +Set of commits reachable from given commit is the commit itself\n>> +and all the commits in its ancestry chain.\n> \n> It's very easy to go around in circles here. The original issue was\n> the A..B notation for the case where A is a direct descendant of B,\n> such that new users, or users more familiar with range notations from\n> elsewhere, would expect that the A..B range is *inclusive*, rather\n> than an open / closed interval. It was the addressing of that problem\n> that lead to the updating of the 'reachability' definition.\n\nAll right, I can see that. It is a worthwhile goal.\n\n> The main part of my sentence formation was to make the 'reachable'\n> part the defining element, rather than being a feature of the set.\n> Maybe it's using the 'set' viewpoint that is distracting?>>\n\nOne one hand, the \"A commit's reachable set is ...\" approach puts\n'reachable' upfront. On the other hand it introduces new terminology,\nnamely 'reachable set' (or 'reachable set of a commit' to be more\nexact)... it doesn't read that well to me, but I am not a native\nspeaker.\n\nBut as I wrote, this is quite all right anyway\n-- \nJakub Narębski\n\n"},{"id":"300485","messageId":"CAF6B88428814389927F9639882BA481@PhilipOakley","threadId":"42687","inReplyTo":"557eb782-ee45-3e33-33bb-aa88817dcd82@gmail.com","subject":"Re: [PATCH v5 09/12] doc: revisions - define `reachable`","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-08-29T19:27:58Z","receivedAt":"2016-08-29T19:28:05Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Jakub Narębski\" \n>W dniu 29.08.2016 o 15:21, Philip Oakley pisze:\n>> From: \"Jakub Narębski\" \n>> Sent: Sunday, August 28, 2016 2:01 PM\n>>> W dniu 12.08.2016 o 09:07, Philip Oakley pisze:\n> [...]\n>\n>>>> +For these commands,\n>>>> +specifying a single revision, using the notation described in the\n>>>> +previous section, means the set of commits `reachable` from the given\n>>>> +commit.\n> [...]\n>>>> +\n>>>> +A commit's reachable set is the commit itself and the commits in\n>>>> +its ancestry chain.\n>>>> +\n>>>\n>>> It is all right, but perhaps it would be better to just repeat:\n>>>\n>>> +Set of commits reachable from given commit is the commit itself\n>>> +and all the commits in its ancestry chain.\n>>\n>> It's very easy to go around in circles here. The original issue was\n>> the A..B notation for the case where A is a direct descendant of B,\n>> such that new users, or users more familiar with range notations from\n>> elsewhere, would expect that the A..B range is *inclusive*, rather\n>> than an open / closed interval. It was the addressing of that problem\n>> that lead to the updating of the 'reachability' definition.\n>\n> All right, I can see that. It is a worthwhile goal.\n>\n>> The main part of my sentence formation was to make the 'reachable'\n>> part the defining element, rather than being a feature of the set.\n>> Maybe it's using the 'set' viewpoint that is distracting?>>\n>\n> One one hand, the \"A commit's reachable set is ...\" approach puts\n> 'reachable' upfront. On the other hand it introduces new terminology,\n> namely 'reachable set' (or 'reachable set of a commit' to be more\n> exact)... it doesn't read that well to me, but I am not a native\n> speaker.\n>\n> But as I wrote, this is quite all right anyway\n> -- \n> Jakub Narębski\n--\nThanks.\n\nPhilip \n\n"},{"id":"300695","messageId":"xmqqbn083o2t.fsf@gitster.mtv.corp.google.com","threadId":"42687","inReplyTo":"20160812234522.7792-1-philipoakley@iee.org","subject":"Re: [PATCH v6 00/12] Update git revisions","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-08-31T16:22:50Z","receivedAt":"2016-08-31T16:26:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley writes:\n\n> These are the quick fixes to Marc's comments to patches 5,6,11,\n> and a consequential change to 12.\n>\n> Only the changed patches are included.\n\nI gave a cursory re-read on the whole thing again, and spotted no\nfurther issue. This has been kept in the \"Undecided\" pile, but I'll\nmark it as \"Will merge to 'next'\" and hope to have it in 'master'\nearly in the post 2.10 cycle.\n\nThanks.\n"}]}