{"thread":{"id":"30960","subject":"[PATCH] Improve revisions.txt","startedAt":"2012-07-05T16:45:16Z","lastAt":"2012-07-23T19:27:54Z","messageCount":9,"participants":["Max Horn","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"194658","messageId":"1341506716-97920-1-git-send-email-max@quendi.de","threadId":"30960","inReplyTo":null,"subject":"[PATCH] Improve revisions.txt","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2012-07-05T16:45:16Z","receivedAt":"2012-07-05T16:45:16Z","isPatch":true,"sender":{"key":"max@quendi.de","avatar":"https://avatars.githubusercontent.com/u/241512?v=4"},"body":"One section talked about when only was defined.\nAnd the description for r1^! was incorrect, talking about \"parents\"\n(which I understand as meaning direct parent commits),\nwhen really all ancestors were meant.\nFinally I added a few more examples (in particular one for \"B..C\")\nthat helped me understand the whole thing.\n\nSigned-off-by: Max Horn \n---\n Documentation/revisions.txt | 20 ++++++++++++--------\n 1 files changed, 12 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 1725661..b452265 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -24,22 +24,22 @@ blobs contained in a commit.\n object referenced by 'refs/heads/master'. If you\n happen to have both 'heads/master' and 'tags/master', you can\n explicitly say 'heads/master' to tell git which one you mean.\n- When ambiguous, a '' is disambiguated by taking the\n+ When ambiguous, a '' is disambiguated by taking the\n first match in the following rules:\n \n- . If '$GIT_DIR/' exists, that is what you mean (this is usually\n+ . If '$GIT_DIR/' exists, that is what you mean (this is usually\n useful only for 'HEAD', 'FETCH_HEAD', 'ORIG_HEAD', 'MERGE_HEAD'\n and 'CHERRY_PICK_HEAD');\n \n- . otherwise, 'refs/' if it exists;\n+ . otherwise, 'refs/' if it exists;\n \n . otherwise, 'refs/tags/' if it exists;\n \n- . otherwise, 'refs/heads/' if it exists;\n+ . otherwise, 'refs/heads/' if it exists;\n \n- . otherwise, 'refs/remotes/' if it exists;\n+ . otherwise, 'refs/remotes/' if it exists;\n \n- . otherwise, 'refs/remotes//HEAD' if it exists.\n+ . otherwise, 'refs/remotes//HEAD' if it exists.\n +\n 'HEAD' names the commit on which you based the changes in the working tree.\n 'FETCH_HEAD' records the branch which you fetched from a remote repository\n@@ -215,8 +215,9 @@ It is the set of commits that are reachable from either one of\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+commits reachable from 'r1' except for 'r1' itself, i.e. all ancestors\n+of 'r1' are included. In contrast to this, 'r1{caret}!' includes commit\n+'r1' but excludes all of its ancestors.\n \n Here are a handful of examples:\n \n@@ -224,7 +225,10 @@ Here are a handful of examples:\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 ^D B C E I J F B C\n+ C I J F C\n C^@ I J F\n+ B^! C B C\n F^! D G H D F\n-- \n1.7.7.5 (Apple Git-26)\n"},{"id":"194665","messageId":"7vpq8aqdzb.fsf@alter.siamese.dyndns.org","threadId":"30960","inReplyTo":"1341506716-97920-1-git-send-email-max@quendi.de","subject":"Re: [PATCH] Improve revisions.txt","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-07-05T18:06:48Z","receivedAt":"2012-07-05T18:06:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Max Horn writes:\n\n> One section talked about when only was defined.\n\nThanks. This is a definite improvement.\n\n> And the description for r1^! was incorrect, talking about \"parents\"\n> (which I understand as meaning direct parent commits),\n> when really all ancestors were meant.\n\nWhat makes ^! exclude \"all ancestors\" is that you fed it to rev-list\nor log. r1^! really means \"mark r1 as interesting, but mark its\ndirect parents as uninteresting\". r1^@ means \"r1's direct parents\nare interesting\". For example, \"git show -s r1^@\" will show the\ndirect parents of r1 but not its ancestors.\n\nWhile there is nothing wrong in the updated descriptin per-se\n(because it is about \"specifying ranges\", aka \"feeding these to\nrev-list or log, here is what happens\"), I am torn about this part\nof the patch. Perhaps ^! and ^@ may also deserve to be described as\na way to give individual revisions (not \"specifying ranges\")?\n\nI dunno.\n\n> Finally I added a few more examples (in particular one for \"B..C\")\n> that helped me understand the whole thing.\n> ...\n> @@ -224,7 +225,10 @@ Here are a handful of examples:\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> ^D B C E I J F B C\n> + C I J F C\n> C^@ I J F\n> + B^! C B C\n> F^! D G H D F\n"},{"id":"194687","messageId":"1341532890-13829-1-git-send-email-max@quendi.de","threadId":"30960","inReplyTo":"7vpq8aqdzb.fsf@alter.siamese.dyndns.org","subject":"[PATCH 1/2] Make documentation more consistent.","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2012-07-06T00:01:29Z","receivedAt":"2012-07-06T00:01:29Z","isPatch":true,"sender":{"key":"max@quendi.de","avatar":"https://avatars.githubusercontent.com/u/241512?v=4"},"body":"Formerly, the documentation for would occasionally say\n instead of . Now it uniformly uses .\n\nSigned-off-by: Max Horn \n---\n Documentation/revisions.txt | 12 ++++++------\n 1 Datei geändert, 6 Zeilen hinzugefügt(+), 6 Zeilen entfernt(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 1725661..f4f6f28 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -24,22 +24,22 @@ blobs contained in a commit.\n object referenced by 'refs/heads/master'. If you\n happen to have both 'heads/master' and 'tags/master', you can\n explicitly say 'heads/master' to tell git which one you mean.\n- When ambiguous, a '' is disambiguated by taking the\n+ When ambiguous, a '' is disambiguated by taking the\n first match in the following rules:\n \n- . If '$GIT_DIR/' exists, that is what you mean (this is usually\n+ . If '$GIT_DIR/' exists, that is what you mean (this is usually\n useful only for 'HEAD', 'FETCH_HEAD', 'ORIG_HEAD', 'MERGE_HEAD'\n and 'CHERRY_PICK_HEAD');\n \n- . otherwise, 'refs/' if it exists;\n+ . otherwise, 'refs/' if it exists;\n \n . otherwise, 'refs/tags/' if it exists;\n \n- . otherwise, 'refs/heads/' if it exists;\n+ . otherwise, 'refs/heads/' if it exists;\n \n- . otherwise, 'refs/remotes/' if it exists;\n+ . otherwise, 'refs/remotes/' if it exists;\n \n- . otherwise, 'refs/remotes//HEAD' if it exists.\n+ . otherwise, 'refs/remotes//HEAD' if it exists.\n +\n 'HEAD' names the commit on which you based the changes in the working tree.\n 'FETCH_HEAD' records the branch which you fetched from a remote repository\n-- \n1.7.11.1.145.g4722b29.dirty\n"},{"id":"194688","messageId":"1341532890-13829-2-git-send-email-max@quendi.de","threadId":"30960","inReplyTo":"1341532890-13829-1-git-send-email-max@quendi.de","subject":"[PATCH 2/2] Document rev^! and rev^@ as revision specifiers","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2012-07-06T00:01:30Z","receivedAt":"2012-07-06T00:01:30Z","isPatch":true,"sender":{"key":"max@quendi.de","avatar":"https://avatars.githubusercontent.com/u/241512?v=4"},"body":"Previously, the rev^! and rev^@ syntax were only described in the\nSPECIFYING RANGES section of revisions.txt, making it a bit harder to\nfind information about it. Moreover, that description was slightly\nconfusing as it described the technical definition of rev^! and rev^@\nwithout making it completely clear what the end effect was.\nThis patch attempts to address this by adding dedicate entries\nfor rev^! and rev^@ in the SPECIFYING REVISIONS section, rewording\nthe existing explanation, and adding two select additional examples.\n\nFinally, it also adds an example for the B..C range syntax, to\nhelp illustrate how it differs from B...C.\n\nSigned-off-by: Max Horn \n---\n Documentation/revisions.txt | 24 +++++++++++++++++++++---\n 1 Datei geändert, 21 Zeilen hinzugefügt(+), 3 Zeilen entfernt(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex f4f6f28..2784298 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -128,6 +128,20 @@ the '$GIT_DIR/refs' directory or from the '$GIT_DIR/packed-refs' file.\n it returns the youngest matching commit which is reachable from\n the '' before '{caret}'.\n \n+'{caret}@', e.g. 'HEAD{caret}@'::\n+ A suffix '{caret}' followed by an at sign\n+ means all parents of ''.\n+ This is somewhat different from the other specifiers in this\n+ section in that it may refer to multiple commits at once.\n+ See also the next section on SPECIFYING RANGES.\n+\n+'{caret}!', e.g. 'HEAD{caret}!'::\n+ A suffix '{caret}' followed by an exclamation mark\n+ means commit '' but forces all of its parents to be excluded. For\n+ commands that deal with a single revision, this is the same as '\".\n+ Hence it is primarily used with commands expecting commit ranges.\n+ See also the next section on SPECIFYING RANGES.\n+\n ':/', e.g. ':/fix nasty bug'::\n A colon, followed by a slash, followed by a text, names\n a commit whose commit message matches the specified regular expression.\n@@ -214,9 +228,10 @@ It is the set of commits that are reachable from either one of\n 'r1' or 'r2' but not from both.\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. Recall that 'r1{caret}@' means all\n+parents of 'r1'. When specifying ranges, this effectively includes\n+all ancestors of 'r1' but excludes 'r1' itself. In contrast to this,\n+'r1{caret}!' includes commit 'r1' but excludes all of its ancestors.\n \n Here are a handful of examples:\n \n@@ -224,7 +239,10 @@ Here are a handful of examples:\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 ^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-- \n1.7.11.1.145.g4722b29.dirty\n"},{"id":"194697","messageId":"7vtxxlnyn1.fsf@alter.siamese.dyndns.org","threadId":"30960","inReplyTo":"1341532890-13829-2-git-send-email-max@quendi.de","subject":"Re: [PATCH 2/2] Document rev^! and rev^@ as revision specifiers","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-07-06T07:21:06Z","receivedAt":"2012-07-06T07:21:06Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Max Horn writes:\n\n> +'{caret}@', e.g. 'HEAD{caret}@'::\n> + A suffix '{caret}' followed by an at sign\n> + means all parents of ''.\n> + This is somewhat different from the other specifiers in this\n> + section in that it may refer to multiple commits at once.\n> + See also the next section on SPECIFYING RANGES.\n\nLooks good.\n\n\n> +'{caret}!', e.g. 'HEAD{caret}!'::\n> + A suffix '{caret}' followed by an exclamation mark\n> + means commit '' but forces all of its parents to be excluded. For\n> + commands that deal with a single revision, this is the same as '\".\n\nIs this sentence correct? \"git commit -C 'HEAD^!'\" might be a\ncommand that expects a single revision, but I do not think it is the\nsame as \"git commit -C HEAD\".\n\n> + Hence it is primarily used with commands expecting commit ranges.\n\nThat is correct.\n"},{"id":"194701","messageId":"D8DF0AED-91D3-45C0-B49E-97E07D21350C@quendi.de","threadId":"30960","inReplyTo":"7vtxxlnyn1.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 2/2] Document rev^! and rev^@ as revision specifiers","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2012-07-06T09:00:54Z","receivedAt":"2012-07-06T09:00:54Z","isPatch":true,"sender":{"key":"max@quendi.de","avatar":"https://avatars.githubusercontent.com/u/241512?v=4"},"body":"\n\nAm 06.07.2012 um 09:21 schrieb Junio C Hamano :\n\n> Max Horn writes:\n> \n>> +'{caret}@', e.g. 'HEAD{caret}@'::\n>> + A suffix '{caret}' followed by an at sign\n>> + means all parents of ''.\n>> + This is somewhat different from the other specifiers in this\n>> + section in that it may refer to multiple commits at once.\n>> + See also the next section on SPECIFYING RANGES.\n> \n> Looks good.\n> \n> \n>> +'{caret}!', e.g. 'HEAD{caret}!'::\n>> + A suffix '{caret}' followed by an exclamation mark\n>> + means commit '' but forces all of its parents to be excluded. For\n>> + commands that deal with a single revision, this is the same as '\".\n> \n> Is this sentence correct? \"git commit -C 'HEAD^!'\" might be a\n> command that expects a single revision, but I do not think it is the\n> same as \"git commit -C HEAD\".\n\nIgnoring the exact words I used for the moment, what I meant is that these two commands should be functionally equivalent. Aren't they? If not, I obviously misunderstand something, and would like to learn more, and add a better explanation.\n\nIf they are equivalent in the sense that the end results are indistinguishable,, and you just dislike the (indeed inaccurate) choice of words, how about replacing \"is the same as\" by \"is [functionally] equivalent\".\n\n\nThank you very much for your reviews,\nMax\n\n\n> \n>> + Hence it is primarily used with commands expecting commit ranges.\n> \n> That is correct.\n> \n"},{"id":"194746","messageId":"7vliiwog0a.fsf@alter.siamese.dyndns.org","threadId":"30960","inReplyTo":"D8DF0AED-91D3-45C0-B49E-97E07D21350C@quendi.de","subject":"Re: [PATCH 2/2] Document rev^! and rev^@ as revision specifiers","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-07-06T19:18:13Z","receivedAt":"2012-07-06T19:18:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Max Horn writes:\n\n>>> +'{caret}!', e.g. 'HEAD{caret}!'::\n>>> + A suffix '{caret}' followed by an exclamation mark\n>>> + means commit '' but forces all of its parents to be excluded. For\n>>> + commands that deal with a single revision, this is the same as '\".\n>> \n>> Is this sentence correct? \"git commit -C 'HEAD^!'\" might be a\n>> command that expects a single revision, but I do not think it is the\n>> same as \"git commit -C HEAD\".\n>\n> Ignoring the exact words I used for the moment, what I meant is that these two commands should be functionally equivalent. Aren't they?\n\nNo. When a single commit is wanted HEAD^! shouldn't be used, and\nthey cannot be functionally equivalent. I haven't tried but I think\n\"commit -C HEAD^!\" would give you a syntax error.\n"},{"id":"194815","messageId":"05708C97-7925-4E45-BA16-374FB38F54D1@quendi.de","threadId":"30960","inReplyTo":"7vliiwog0a.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 2/2] Document rev^! and rev^@ as revision specifiers","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2012-07-09T15:02:19Z","receivedAt":"2012-07-09T15:02:19Z","isPatch":true,"sender":{"key":"max@quendi.de","avatar":"https://avatars.githubusercontent.com/u/241512?v=4"},"body":"> \nOn 06.07.2012, at 21:18, Junio C Hamano wrote:\n\n> Max Horn writes:\n> \n>>>> +'{caret}!', e.g. 'HEAD{caret}!'::\n>>>> + A suffix '{caret}' followed by an exclamation mark\n>>>> + means commit '' but forces all of its parents to be excluded. For\n>>>> + commands that deal with a single revision, this is the same as '\".\n>>> \n>>> Is this sentence correct? \"git commit -C 'HEAD^!'\" might be a\n>>> command that expects a single revision, but I do not think it is the\n>>> same as \"git commit -C HEAD\".\n>> \n>> Ignoring the exact words I used for the moment, what I meant is that these two commands should be functionally equivalent. Aren't they?\n> \n> No. When a single commit is wanted HEAD^! shouldn't be used, and\n> they cannot be functionally equivalent. I haven't tried but I think\n> \"commit -C HEAD^!\" would give you a syntax error.\n> \n\nIndeed, it says\n fatal: could not lookup commit HEAD^!\n\nI'll iterate over this once more.\n\nCheers,\nMax"},{"id":"195556","messageId":"7vliial1l1.fsf@alter.siamese.dyndns.org","threadId":"30960","inReplyTo":"05708C97-7925-4E45-BA16-374FB38F54D1@quendi.de","subject":"Re: [PATCH 2/2] Document rev^! and rev^@ as revision specifiers","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-07-23T19:27:54Z","receivedAt":"2012-07-23T19:27:54Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Max Horn writes:\n\n>> \n> On 06.07.2012, at 21:18, Junio C Hamano wrote:\n>\n>> Max Horn writes:\n>> \n>>>>> +'{caret}!', e.g. 'HEAD{caret}!'::\n>>>>> + A suffix '{caret}' followed by an exclamation mark\n>>>>> + means commit '' but forces all of its parents to be excluded. For\n>>>>> + commands that deal with a single revision, this is the same as '\".\n>>>> \n>>>> Is this sentence correct? \"git commit -C 'HEAD^!'\" might be a\n>>>> command that expects a single revision, but I do not think it is the\n>>>> same as \"git commit -C HEAD\".\n>>> \n>>> Ignoring the exact words I used for the moment, what I meant is\n>>> that these two commands should be functionally\n>>> equivalent. Aren't they?\n>> \n>> No. When a single commit is wanted HEAD^! shouldn't be used, and\n>> they cannot be functionally equivalent. I haven't tried but I think\n>> \"commit -C HEAD^!\" would give you a syntax error.\n>\n> Indeed, it says\n> fatal: could not lookup commit HEAD^!\n>\n> I'll iterate over this once more.\n\nLet's do this instead.\n\n-- >8 --\nSubject: Enumerate revision range specifiers in the documentation\n\nIt was a bit hard to learn how ^@, ^! and various other\nforms of range specification are used, because they were discussed\nmostly in the prose part of the documentation, unlike various forms\nof extended SHA-1 expressions that are listed in enumerated list.\n\nAlso add a few more examples showing use of , .. and\n^! forms, stolen from a patch by Max Horn.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/revisions.txt | 31 +++++++++++++++++++++++++++++++\n 1 file changed, 31 insertions(+)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex f4f6f28..6506ec6 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -218,13 +218,44 @@ 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 \n+To summarize:\n+\n+''::\n+\tInclude commits that are reachable from (i.e. ancestors of)\n+\t.\n+\n+'{caret}'::\n+\tExclude commits that are reachable from (i.e. ancestors of)\n+\t.\n+\n+'..'::\n+\tInclude commits that are reachable from but exclude\n+\tthose that are reachable from .\n+\n+'...'::\n+\tInclude commits that are reachable from either or\n+\t but exclude those that are reachable from both.\n+\n+'{caret}@', e.g. 'HEAD{caret}@'::\n+ A suffix '{caret}' followed by an at sign is the same as listing\n+ all parents of '' (meaning, include anything reachable from\n+ its parents, but not the commit itself).\n+\n+'{caret}!', e.g. 'HEAD{caret}!'::\n+ A suffix '{caret}' followed by an exclamation mark is the same\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 \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 ^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"}]}