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

From: Junio C Hamano <[email-masked]>
Date: Thu, 31 Oct 2013 13:27:11 -0700

Felipe Contreras <[email-masked]> writes:

> On Thu, Oct 31, 2013 at 1:00 PM, Junio C Hamano <[email-masked]> wrote:
>> Felipe Contreras <[email-masked]> writes:
>>
>>> On Thu, Oct 31, 2013 at 12:11 PM, Junio C Hamano <[email-masked]> wrote:
>>>> Felipe Contreras <[email-masked]> writes:
>>>
>>>>> --- a/Documentation/git-pull.txt
>>>>> +++ b/Documentation/git-pull.txt
>>>>> @@ -39,7 +39,7 @@ Assume the following history exists and the current branch is
>>>>>  "`master`":
>>>>>
>>>>>  ------------
>>>>> -       A---B---C master on origin
>>>>> +       A---B---C origin/master
>>>>>        /
>>>>>      D---E---F---G master
>>>>>  ------------
>>>>
>>>> This change is wrong; the illustration depicts the distributed world
>>>> (i.e. a fetch has not happened yet).
>>>
>>> That is an irrelevant implementation detail, specially at this high
>>> level. In the user's mind origin/master means master on origin.
>>
>> You are wrong.  In the user's mind, origin/master means the commit
>> that used to be at master on origin, and the point of this
>> illustration is to make them understand that they live in a
>> distributed world, where their last observation will go stale over
>> time.
>
> Wrong. That would make sense in 'git fetch', but here the point of the
> illustration is to make them understand what 'git pull' will do,
> namely a merge.
>
> Which refs point to C at which points in time irrelevant information,
> the user wants to know that 'git pull' will create a merge.

Merge with what, and how do the users know what will be merged?

Think.

The users need to learn that origin/master they were told to use
with "git log origin/master.." etc. trails reality, "git fetch" is
how they can get them in sync, and the reason they do not need to
run "git fetch" separately when they "git pull" is because it is run
for them internally.

That is what the illustration and the paragraph that follows teach
them.

I've said enough on this.