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

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: Oct 31, 2013, 19:51 UTC
Message-ID: <CAMP44s1-pVDoLrEC9m0J+fRCxnvMb+P0ANMxS7vzBhFub_Yv6Q@mail.gmail.com>
In-Reply-To: <xmqqob655kqi.fsf@gitster.dls.corp.google.com>

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

Show 28 quoted lines

> 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.

Show 17 quoted lines

>> If you want to be pedantic, this is the "reality":
>>
>>   ------------
>>       D---E---F---G master
>>   ------------
>
> You are wrong again.  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.

Wrong. You probably mean:

------------
          A---B---C master on origin
         /
    D---E origin/master
         \
          F---G master
------------

But 'master on origin' doesn't exist in "reality" according to you, so:

------------
    D---E origin/master
         \
          F---G master
------------

-- 
Felipe Contreras