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

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: Oct 31, 2013, 21:15 UTC
Message-ID: <CAMP44s0VTfz5OpVqLbyTSSWVtOkTV5hVn0ofDcA16qDjWFfyhw@mail.gmail.com>
In-Reply-To: <xmqqr4b1425c.fsf@gitster.dls.corp.google.com>

On Thu, Oct 31, 2013 at 2:27 PM, Junio C Hamano <gitster@pobox.com> wrote:

Show 40 quoted lines

> Felipe Contreras <felipe.contreras@gmail.com> writes:
>
>> On Thu, Oct 31, 2013 at 1:00 PM, Junio C Hamano <gitster@pobox.com> wrote:
>>> Felipe Contreras <felipe.contreras@gmail.com> writes:
>>>
>>>> On Thu, Oct 31, 2013 at 12:11 PM, Junio C Hamano <gitster@pobox.com> wrote:
>>>>> Felipe Contreras <felipe.contreras@gmail.com> 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,

Merge with C.

> and how do the users know what will be merged?

They don't, not after they run 'git pull' anyway.

> The users need to learn that origin/master they were told to use
> with "git log origin/master.." etc. trails reality,

Yes, but they don't *need* to learn it *right now*. All they need to learn is that 'git pull' will do a merge with 'master' from 'origin', AKA 'origin/master'.

-- 
Felipe Contreras