[PATCH] Documentation: Simplify git-rev-parse's example

[PATCH] Documentation: Simplify git-rev-parse's example

[Pieter de Bie]

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 <pdebie@ai.rug.nl>
---

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

Re: [PATCH] Documentation: Simplify git-rev-parse's example

[Jon Loeliger]

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 <pdebie@ai.rug.nl>
> ---
> 
> 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

Re: [PATCH] Documentation: Simplify git-rev-parse's example

[Junio C Hamano]

Jon Loeliger <jdl@freescale.com> 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 <pdebie@ai.rug.nl>
>> ---
>>
>> 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.

Re: [PATCH] Documentation: Simplify git-rev-parse's example

[Pieter de Bie]

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.

Re: [PATCH] Documentation: Simplify git-rev-parse's example

[Junio C Hamano]

Pieter de Bie <pdebie@ai.rug.nl> 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.