Re: [PATCH 03/16] pull: cleanup documentation
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Oct 31, 2013, 20:43 UTC
- Message-ID
- <xmqqfvrh41e0.fsf@gitster.dls.corp.google.com>
- In-Reply-To
- <xmqqzjpp447x.fsf@gitster.dls.corp.google.com>
Junio C Hamano <gitster@pobox.com> writes:
Show 22 quoted lines
> 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 ------------