# [PATCH] Documentation: Simplify git-rev-parse's example 5 messages from 2008-06-19 to 2008-06-19. Participants: Pieter de Bie, Jon Loeliger, Junio C Hamano. Thread: https://gitlist.dev/t/14035 ## Pieter de Bie, 2008-06-19 11:12 Subject: [PATCH] Documentation: Simplify git-rev-parse's example Message-ID: <1213873976-4192-1-git-send-email-pdebie@ai.rug.nl> URL: https://gitlist.dev/e/1213873976-4192-1-git-send-email-pdebie%40ai.rug.nl ``` This example was overly complex and therefore confusing. The commits have been renamed to start the oldest commit with "A" and working up from there. Also, this removes some commits so the graph is simpler. Finally the graph has been reversed in direction to make it more like gitk. Signed-off-by: Pieter de Bie --- This was created after some discussion in #git about how this was confusing. The consesus was that this example is better. Documentation/git-rev-parse.txt | 69 ++++++++++++++++++++------------------- 1 files changed, 35 insertions(+), 34 deletions(-) diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 9e273bc..ddeb496 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -243,34 +243,34 @@ blobs contained in a commit. (typically the current branch), and stage 3 is the version from the branch being merged. -Here is an illustration, by Jon Loeliger. Both commit nodes B -and C are parents of commit node A. Parent commits are ordered -left-to-right. +Here is an illustration. The newest commits are on the top. +Commit H is a merge commit: its parents are both commit nodes F and G. +Parent commits are ordered left-to-right. ........................................ -G H I J - \ / \ / - D E F - \ | / \ - \ | / | - \|/ | - B C - \ / - \ / - A -........................................ - A = = A^0 - B = A^ = A^1 = A~1 - C = A^2 = A^2 - D = A^^ = A^1^1 = A~2 - E = B^2 = A^^2 - F = B^3 = A^^3 - G = A^^^ = A^1^1^1 = A~3 - H = D^2 = B^^2 = A^^^2 = A~2^2 - I = F^ = B^3^ = A^^3^ - J = F^2 = B^3^2 = A^^3^2 + H + / \ + / \ + F G + / \ | + / \ | + / \ / + D E + / \ | +A B C + +........................................ + H = H^0 + F = H^ = H^1 = H~1 + G = H^2 + D = H^^ = H^1^1 = H~2 + E = F^2 = H^^2 + E = F^3 = H^^3 = H^2^ + A = H^^^ = H^1^1^1 = H~3 + B = D^ = H^^^2 = H~2^2 + C = E^ = H^^3^ SPECIFYING RANGES ----------------- @@ -302,16 +302,17 @@ and its parent commits exists. `r1{caret}@` notation means all parents of `r1`. `r1{caret}!` includes commit `r1` but excludes its all parents. -Here are a handful of examples: - - D G H D - D F G H I J D F - ^G D H D - ^D B E I J F B - B...C G H D E B C - ^D B C E I J F B C - C^@ I J F - F^! D G H D F +Here are a handful of examples. Note that there is no ordering in +the set of commits. See also linkgit:git-rev-list[1]'s --topo-order +and --date-order. + + D A B D + D E A B C D E + ^A D B D + ^D F C E F + F...G A B D F G + D^@ A B + E^! D A B D E PARSEOPT -------- -- 1.5.6.rc1.153.gc1d96 ``` ## Jon Loeliger, 2008-06-19 19:12 Subject: Re: [PATCH] Documentation: Simplify git-rev-parse's example Message-ID: <485AAF82.3030209@freescale.com> URL: https://gitlist.dev/e/485AAF82.3030209%40freescale.com In-Reply-To: <1213873976-4192-1-git-send-email-pdebie@ai.rug.nl> ``` Pieter de Bie wrote: > This example was overly complex and therefore confusing. > The commits have been renamed to start the oldest commit with "A" > and working up from there. Also, this removes some commits so the graph > is simpler. Finally the graph has been reversed in direction to make it > more like gitk. > > Signed-off-by: Pieter de Bie > --- > > This was created after some discussion in #git about how this was confusing. > The consesus was that this example is better. How is this a vast improvement? I could see that inverting it top-to-bottom would be more consistent with gitk or show-branch output. Your example doesn't have a 3-parent commit, though, and it isn't _that_ much simpler otherwise... So this is really better _how_? Oh, right, of course. It removes my name. Got it. :-) jdl ``` ## Junio C Hamano, 2008-06-19 19:33 Subject: Re: [PATCH] Documentation: Simplify git-rev-parse's example Message-ID: <7v8wx1te20.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7v8wx1te20.fsf%40gitster.siamese.dyndns.org In-Reply-To: <485AAF82.3030209@freescale.com> ``` Jon Loeliger writes: > Pieter de Bie wrote: >> This example was overly complex and therefore confusing. >> The commits have been renamed to start the oldest commit with "A" >> and working up from there. Also, this removes some commits so the graph >> is simpler. Finally the graph has been reversed in direction to make it >> more like gitk. >> >> Signed-off-by: Pieter de Bie >> --- >> >> This was created after some discussion in #git about how this was confusing. >> The consesus was that this example is better. > > How is this a vast improvement? > > I could see that inverting it top-to-bottom would > be more consistent with gitk or show-branch output. > Your example doesn't have a 3-parent commit, though, > and it isn't _that_ much simpler otherwise... > > So this is really better _how_? > > Oh, right, of course. It removes my name. Got it. :-) I agree that the patch should have just flipped the tree upside down without changing the shape of the history the section talks about. Yet another improvement would have been turning it sideways, not upside down, because that is how we typically write history in our documentation (time flows from left to right -- see e.g. git-rebase.txt). I happen to think the last point you raise is an improvement. It will quickly become unreadble after a while if we credit individual authors for every paragraph in-text, and it always bothered me to see somebody's name (don't get me wrong -- this is not because it is your name nor because it is not my name, but because it _is_ a name), there but I wasn't bold enough to remove it without discussion. ``` ## Pieter de Bie, 2008-06-19 23:02 Subject: Re: [PATCH] Documentation: Simplify git-rev-parse's example Message-ID: URL: https://gitlist.dev/e/D6812FD2-F61D-4813-95B4-4FCCDE35C418%40ai.rug.nl In-Reply-To: <7v8wx1te20.fsf@gitster.siamese.dyndns.org> ``` On 19 jun 2008, at 21:33, Junio C Hamano wrote: >> How is this a vast improvement? >> >> I could see that inverting it top-to-bottom would >> be more consistent with gitk or show-branch output. >> Your example doesn't have a 3-parent commit, though, >> and it isn't _that_ much simpler otherwise... >> >> So this is really better _how_? >> >> Oh, right, of course. It removes my name. Got it. :-) > > I agree that the patch should have just flipped the tree upside down > without changing the shape of the history the section talks about. I tried to make it less of a monster while still keeping examples of all possibilities, which is why I removed two of the nodes. > Yet another improvement would have been turning it sideways, not > upside > down, because that is how we typically write history in our > documentation > (time flows from left to right -- see e.g. git-rebase.txt). I tried to do that, but wasn't able to create a nice-looking graph, which is why I settled on this version. > I happen to think the last point you raise is an improvement. It will > quickly become unreadble after a while if we credit individual > authors for > every paragraph in-text, and it always bothered me to see somebody's > name > (don't get me wrong -- this is not because it is your name nor > because it > is not my name, but because it _is_ a name), there but I wasn't bold > enough to remove it without discussion. I did not want to keep a name with something that was modified, since it might not get the author's approval. That's why I removed it. I also agree that it reads better. ``` ## Junio C Hamano, 2008-06-19 23:28 Subject: Re: [PATCH] Documentation: Simplify git-rev-parse's example Message-ID: <7v63s5rolr.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7v63s5rolr.fsf%40gitster.siamese.dyndns.org In-Reply-To: ``` Pieter de Bie writes: > On 19 jun 2008, at 21:33, Junio C Hamano wrote: > >>> How is this a vast improvement? >>> >>> I could see that inverting it top-to-bottom would >>> be more consistent with gitk or show-branch output. >>> Your example doesn't have a 3-parent commit, though, >>> and it isn't _that_ much simpler otherwise... >>> >>> So this is really better _how_? >>> >>> Oh, right, of course. It removes my name. Got it. :-) >> >> I agree that the patch should have just flipped the tree upside down >> without changing the shape of the history the section talks about. > > I tried to make it less of a monster while still keeping examples of > all possibilities, which is why I removed two of the nodes. I do not care _that_ deeply myself, but judging from how often the word Octopus comes up on this list (even though I do not think we would want to especially encourage the practice), I think it is a disservice to drop an octopus from the section that teaches how to name a commit in an ancestry graph. ```