From: Junio C Hamano Date: Thu, 31 Oct 2013 20:27:11 GMT Subject: Re: [PATCH 03/16] pull: cleanup documentation Message-ID: In-Reply-To: Felipe Contreras writes: > On Thu, Oct 31, 2013 at 1:00 PM, Junio C Hamano wrote: >> Felipe Contreras writes: >> >>> On Thu, Oct 31, 2013 at 12:11 PM, Junio C Hamano wrote: >>>> Felipe Contreras 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.