[PATCH] git-pull.txt: Add picture to --rebase option

[PATCH] git-pull.txt: Add picture to --rebase option

[jari.aalto]

From: Jari Aalto <jari.aalto@cante.net>

Illustrate what are the effects of the the option.

Signed-off-by: Jari Aalto <jari.aalto@cante.net>
---
 Documentation/git-pull.txt |   12 ++++++++++++
 1 files changed, 12 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index e47361f..25eb6de 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -106,6 +106,18 @@ This is a potentially _dangerous_ mode of operation.
 It rewrites history, which does not bode well when you
 published that history already.  Do *not* use this option
 unless you have read linkgit:git-rebase[1] carefully.
++
+The effects of this option are:
+------------
+    [initial]
+    o---o---o---A--B   Your work in commit A and B
+
+    [git pull --rebase]
+    o---o---o---*---*--A--B
+                |   |
+                New updates merged in. Your work is rebased
+                on top of them.
+------------
 
 --no-rebase::
 	Override earlier --rebase.
-- 
1.7.2.3

Re: [PATCH] git-pull.txt: Add picture to --rebase option

[Jakub Narebski]

jari.aalto@cante.net writes:

> From: Jari Aalto <jari.aalto@cante.net>
> 
> Illustrate what are the effects of the the option.
> 
> Signed-off-by: Jari Aalto <jari.aalto@cante.net>

> ++
> +The effects of this option are:
> +------------
> +    [initial]
> +    o---o---o---A--B   Your work in commit A and B
> +
> +    [git pull --rebase]
> +    o---o---o---*---*--A--B
> +                |   |
> +                New updates merged in. Your work is rebased
> +                on top of them.
> +------------

Good idea.  Thanks.

-- 
Jakub Narebski
Poland
ShadeHawk on #git

Re: [PATCH] git-pull.txt: Add picture to --rebase option

[Junio C Hamano]

jari.aalto@cante.net writes:

> From: Jari Aalto <jari.aalto@cante.net>
>
> Illustrate what are the effects of the the option.
>
> Signed-off-by: Jari Aalto <jari.aalto@cante.net>
> ---
>  Documentation/git-pull.txt |   12 ++++++++++++
>  1 files changed, 12 insertions(+), 0 deletions(-)
>
> diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
> index e47361f..25eb6de 100644
> --- a/Documentation/git-pull.txt
> +++ b/Documentation/git-pull.txt
> @@ -106,6 +106,18 @@ This is a potentially _dangerous_ mode of operation.
>  It rewrites history, which does not bode well when you
>  published that history already.  Do *not* use this option
>  unless you have read linkgit:git-rebase[1] carefully.
> ++
> +The effects of this option are:
> +------------
> +    [initial]
> +    o---o---o---A--B   Your work in commit A and B
> +
> +    [git pull --rebase]
> +    o---o---o---*---*--A--B
> +                |   |
> +                New updates merged in. Your work is rebased
> +                on top of them.
> +------------

While I think it is a good idea to have an illustration for pull-rebase, I
am not happy with the above drawing.

An obvious nit is the wording "merged in", but more importantly, the
reader won't be told three important facts about what you are trying to
illustrate:

 - how these two '*' originally happened;
 - how they are preserved across the operation; as opposed to
 - how your own A and B are rewritten.

Also I do not think it is necessary to introduce an initial state separate
from the one we already have established earlier in the documentation;
it will reduce the mental burden of the readers if we set the stage only
once, and show two different outcomes starting from that same state.

It would be better to add something like the following after the first
illustration on the page that shows how the default `git pull`
consolidates the histories by creating a merge commit `H`, immediately
after "See linkgit:git-merge[1] for details,...".

    [NOTE] 
    The command can also be told to consolidate your work on top of what
    the other side did by rebasing, instead of merging, with `git pull
    --rebase`.  Starting from the same state as illustrated above, it
    would create a new history like the following picture by rewriting
    your commits F and G to sit on top of the history the other side
    created:

              A---B---C master on origin
             /         \
        D---E---F---G   F'--G' master

    Your original commits F and G are abandoned to be garbage collected,
    and your `master` branch will point at the tip of the rewritten
    history.

Note that I did *NOT* run AsciiDoc on the above---this is not a suggestion
on formatting, but on the contents.