jari.aalto@xxxxxxxxx writes:
> From: Jari Aalto <jari.aalto@xxxxxxxxx>
>
> Illustrate what are the effects of the the option.
>
> Signed-off-by: Jari Aalto <jari.aalto@xxxxxxxxx>
> ---
> 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.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html