Re: [PATCH 03/16] pull: cleanup documentation

[Junio C Hamano <gitster@pobox.com>]

Junio C Hamano <gitster@pobox.com> writes:

> Max Horn <max@quendi.de> writes:
>
>>> ... The "reality" is more like this:
>>> 
>>>      origin/master in your repository
>>>      |
>>>      v
>>>      A---B---C master at origin
>>>     /
>>>    D---E---F---G master in your repository
>>> 
>>> if you really want to write origin/master somewhere in this
>>> illustration.
>>
>> Actually, I kind of like that. After just reading the existing
>> phrasing in git-pull.txt, I doubt that a newbie would catch the
>> difference between "origin/master" and "master at origin". With this
>> illustration, it's very clearly conveyed that there is a difference.
>
> Yeah, after re-reading the part of the documentation with the
> illustration replaced with the above, I was coming to the same
> conclusion.

As Felipe spotted in his response, "A" is not something you already
have, so the picture need to look like the amended patch below.

The other reason the original did not say "origin/master" is because
this holds true even if you do not have such a remote-tracking
branch for the master at the origin, but the illustration that shows
the history after "git pull" finishes spells remotes/origin/master
out, so I think it would be an improvement to make the two pictures
consistent by drawing where the origin/master is before this "git
pull" is run.

Something like this, perhaps.  Note that I think "on" sounds funny
and it should probably be "at" instead, but this weatherbaloon patch
does not change it.

-- >8 --
Subject: doc/pull: clarify the illustrations

The second illustration that shows the history after "git pull"
spelled the remote-tracking branch with "remotes/" prefix, which
is not necessary.  Drop it.

To match the assumption that a remote-tracking branch is used to
keep track of the advancement of the master at the origin, update
the first illustration that shows the history before "git pull"
to show the distinction between the master currently at origin and
the stale origin/master remote-tracking branch.

Noticed-by: Felipe Contreras <felipe.contreras@gmail.com>
Helped-by: Max Horn <max@quendi.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-pull.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index beea10b..e83f3ce 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -42,6 +42,8 @@ Assume the following history exists and the current branch is
 	  A---B---C master on origin
 	 /
     D---E---F---G master
+        ^
+	origin/master in your repository
 ------------
 
 Then "`git pull`" will fetch and replay the changes from the remote
@@ -51,7 +53,7 @@ result in a new commit along with the names of the two parent commits
 and a log message from the user describing the changes.
 
 ------------
-	  A---B---C remotes/origin/master
+	  A---B---C origin/master
 	 /         \
     D---E---F---G---H master
 ------------