{"thread":{"id":"14035","subject":"[PATCH] Documentation: Simplify git-rev-parse's example","startedAt":"2008-06-19T11:12:56Z","lastAt":"2008-06-19T23:28:48Z","messageCount":5,"participants":["Pieter de Bie","Jon Loeliger","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"80310","messageId":"1213873976-4192-1-git-send-email-pdebie@ai.rug.nl","threadId":"14035","inReplyTo":null,"subject":"[PATCH] Documentation: Simplify git-rev-parse's example","fromName":"Pieter de Bie","fromEmail":"pdebie@ai.rug.nl","sentAt":"2008-06-19T11:12:56Z","receivedAt":"2008-06-19T11:12:56Z","isPatch":true,"sender":{"key":"pdebie@ai.rug.nl","avatar":null},"body":"This example was overly complex and therefore confusing.\nThe commits have been renamed to start the oldest commit with \"A\"\nand working up from there. Also, this removes some commits so the graph\nis simpler. Finally the graph has been reversed in direction to make it\nmore like gitk.\n\nSigned-off-by: Pieter de Bie \n---\n\nThis was created after some discussion in #git about how this was confusing.\nThe consesus was that this example is better.\n\n Documentation/git-rev-parse.txt | 69 ++++++++++++++++++++-------------------\n 1 files changed, 35 insertions(+), 34 deletions(-)\n\ndiff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt\nindex 9e273bc..ddeb496 100644\n--- a/Documentation/git-rev-parse.txt\n+++ b/Documentation/git-rev-parse.txt\n@@ -243,34 +243,34 @@ blobs contained in a commit.\n (typically the current branch), and stage 3 is the version from\n the branch being merged.\n \n-Here is an illustration, by Jon Loeliger. Both commit nodes B\n-and C are parents of commit node A. Parent commits are ordered\n-left-to-right.\n+Here is an illustration. The newest commits are on the top.\n+Commit H is a merge commit: its parents are both commit nodes F and G.\n+Parent commits are ordered left-to-right.\n \n ........................................\n-G H I J\n- \\ / \\ /\n- D E F\n- \\ | / \\\n- \\ | / |\n- \\|/ |\n- B C\n- \\ /\n- \\ /\n- A\n-........................................\n \n- A = = A^0\n- B = A^ = A^1 = A~1\n- C = A^2 = A^2\n- D = A^^ = A^1^1 = A~2\n- E = B^2 = A^^2\n- F = B^3 = A^^3\n- G = A^^^ = A^1^1^1 = A~3\n- H = D^2 = B^^2 = A^^^2 = A~2^2\n- I = F^ = B^3^ = A^^3^\n- J = F^2 = B^3^2 = A^^3^2\n+ H\n+ / \\\n+ / \\\n+ F G\n+ / \\ |\n+ / \\ |\n+ / \\ /\n+ D E\n+ / \\ |\n+A B C\n+\n+........................................\n \n+ H = H^0\n+ F = H^ = H^1 = H~1\n+ G = H^2\n+ D = H^^ = H^1^1 = H~2\n+ E = F^2 = H^^2\n+ E = F^3 = H^^3 = H^2^\n+ A = H^^^ = H^1^1^1 = H~3\n+ B = D^ = H^^^2 = H~2^2\n+ C = E^ = H^^3^\n \n SPECIFYING RANGES\n -----------------\n@@ -302,16 +302,17 @@ and its parent commits exists. `r1{caret}@` notation means all\n parents of `r1`. `r1{caret}!` includes commit `r1` but excludes\n its all parents.\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 G H D E B C\n- ^D B C E I J F B C\n- C^@ I J F\n- F^! D G H D F\n+Here are a handful of examples. Note that there is no ordering in\n+the set of commits. See also linkgit:git-rev-list[1]'s --topo-order\n+and --date-order.\n+\n+ D A B D\n+ D E A B C D E\n+ ^A D B D\n+ ^D F C E F\n+ F...G A B D F G\n+ D^@ A B\n+ E^! D A B D E\n \n PARSEOPT\n --------\n-- \n1.5.6.rc1.153.gc1d96\n"},{"id":"80354","messageId":"485AAF82.3030209@freescale.com","threadId":"14035","inReplyTo":"1213873976-4192-1-git-send-email-pdebie@ai.rug.nl","subject":"Re: [PATCH] Documentation: Simplify git-rev-parse's example","fromName":"Jon Loeliger","fromEmail":"jdl@freescale.com","sentAt":"2008-06-19T19:12:02Z","receivedAt":"2008-06-19T19:12:02Z","isPatch":true,"sender":{"key":"jdl@jdl.com","avatar":"https://gravatar.com/avatar/75ce9a10b151acd2c28ec4ab2136dba7b2ff1634530bd04b155981a749d08a64?d=mp&s=160"},"body":"Pieter de Bie wrote:\n> This example was overly complex and therefore confusing.\n> The commits have been renamed to start the oldest commit with \"A\"\n> and working up from there. Also, this removes some commits so the graph\n> is simpler. Finally the graph has been reversed in direction to make it\n> more like gitk.\n> \n> Signed-off-by: Pieter de Bie \n> ---\n> \n> This was created after some discussion in #git about how this was confusing.\n> The consesus was that this example is better.\n\nHow is this a vast improvement?\n\nI could see that inverting it top-to-bottom would\nbe more consistent with gitk or show-branch output.\nYour example doesn't have a 3-parent commit, though,\nand it isn't _that_ much simpler otherwise...\n\nSo this is really better _how_?\n\nOh, right, of course. It removes my name. Got it. :-)\n\njdl\n"},{"id":"80358","messageId":"7v8wx1te20.fsf@gitster.siamese.dyndns.org","threadId":"14035","inReplyTo":"485AAF82.3030209@freescale.com","subject":"Re: [PATCH] Documentation: Simplify git-rev-parse's example","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-06-19T19:33:43Z","receivedAt":"2008-06-19T19:33:43Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jon Loeliger writes:\n\n> Pieter de Bie wrote:\n>> This example was overly complex and therefore confusing.\n>> The commits have been renamed to start the oldest commit with \"A\"\n>> and working up from there. Also, this removes some commits so the graph\n>> is simpler. Finally the graph has been reversed in direction to make it\n>> more like gitk.\n>>\n>> Signed-off-by: Pieter de Bie \n>> ---\n>>\n>> This was created after some discussion in #git about how this was confusing.\n>> The consesus was that this example is better.\n>\n> How is this a vast improvement?\n>\n> I could see that inverting it top-to-bottom would\n> be more consistent with gitk or show-branch output.\n> Your example doesn't have a 3-parent commit, though,\n> and it isn't _that_ much simpler otherwise...\n>\n> So this is really better _how_?\n>\n> Oh, right, of course. It removes my name. Got it. :-)\n\nI agree that the patch should have just flipped the tree upside down\nwithout changing the shape of the history the section talks about.\n\nYet another improvement would have been turning it sideways, not upside\ndown, because that is how we typically write history in our documentation\n(time flows from left to right -- see e.g. git-rebase.txt).\n\nI happen to think the last point you raise is an improvement. It will\nquickly become unreadble after a while if we credit individual authors for\nevery paragraph in-text, and it always bothered me to see somebody's name\n(don't get me wrong -- this is not because it is your name nor because it\nis not my name, but because it _is_ a name), there but I wasn't bold\nenough to remove it without discussion.\n"},{"id":"80399","messageId":"D6812FD2-F61D-4813-95B4-4FCCDE35C418@ai.rug.nl","threadId":"14035","inReplyTo":"7v8wx1te20.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] Documentation: Simplify git-rev-parse's example","fromName":"Pieter de Bie","fromEmail":"pdebie@ai.rug.nl","sentAt":"2008-06-19T23:02:07Z","receivedAt":"2008-06-19T23:02:07Z","isPatch":true,"sender":{"key":"pdebie@ai.rug.nl","avatar":null},"body":"\nOn 19 jun 2008, at 21:33, Junio C Hamano wrote:\n\n>> How is this a vast improvement?\n>>\n>> I could see that inverting it top-to-bottom would\n>> be more consistent with gitk or show-branch output.\n>> Your example doesn't have a 3-parent commit, though,\n>> and it isn't _that_ much simpler otherwise...\n>>\n>> So this is really better _how_?\n>>\n>> Oh, right, of course. It removes my name. Got it. :-)\n>\n> I agree that the patch should have just flipped the tree upside down\n> without changing the shape of the history the section talks about.\n\nI tried to make it less of a monster while still keeping examples of\nall possibilities, which is why I removed two of the nodes.\n\n> Yet another improvement would have been turning it sideways, not \n> upside\n> down, because that is how we typically write history in our \n> documentation\n> (time flows from left to right -- see e.g. git-rebase.txt).\n\nI tried to do that, but wasn't able to create a nice-looking graph, \nwhich\nis why I settled on this version.\n\n> I happen to think the last point you raise is an improvement. It will\n> quickly become unreadble after a while if we credit individual \n> authors for\n> every paragraph in-text, and it always bothered me to see somebody's \n> name\n> (don't get me wrong -- this is not because it is your name nor \n> because it\n> is not my name, but because it _is_ a name), there but I wasn't bold\n> enough to remove it without discussion.\n\nI did not want to keep a name with something that was modified, since it\nmight not get the author's approval. That's why I removed it. I also \nagree\nthat it reads better.\n"},{"id":"80416","messageId":"7v63s5rolr.fsf@gitster.siamese.dyndns.org","threadId":"14035","inReplyTo":"D6812FD2-F61D-4813-95B4-4FCCDE35C418@ai.rug.nl","subject":"Re: [PATCH] Documentation: Simplify git-rev-parse's example","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-06-19T23:28:48Z","receivedAt":"2008-06-19T23:28:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Pieter de Bie writes:\n\n> On 19 jun 2008, at 21:33, Junio C Hamano wrote:\n>\n>>> How is this a vast improvement?\n>>>\n>>> I could see that inverting it top-to-bottom would\n>>> be more consistent with gitk or show-branch output.\n>>> Your example doesn't have a 3-parent commit, though,\n>>> and it isn't _that_ much simpler otherwise...\n>>>\n>>> So this is really better _how_?\n>>>\n>>> Oh, right, of course. It removes my name. Got it. :-)\n>>\n>> I agree that the patch should have just flipped the tree upside down\n>> without changing the shape of the history the section talks about.\n>\n> I tried to make it less of a monster while still keeping examples of\n> all possibilities, which is why I removed two of the nodes.\n\nI do not care _that_ deeply myself, but judging from how often the word\nOctopus comes up on this list (even though I do not think we would want to\nespecially encourage the practice), I think it is a disservice to drop an\noctopus from the section that teaches how to name a commit in an ancestry\ngraph.\n"}]}