Re: [PATCH 1/5] fetch doc: update introductory part for clarity

[Junio C Hamano <gitster@pobox.com>]

Marc Branchaud <marcnarc@xiplink.com> writes:

> On 14-05-29 06:42 PM, Junio C Hamano wrote:
>>  - "Branches" is a more common way to say "heads" in these days.
>> 
>>  - Remote-tracking branches are used a lot more these days and it is
>>    worth mentioning that it is one of the primary side effects of
>>    the command to update them.
>> 
>>  - Avoid "X. That means Y."  If Y is easier to understand to
>>    readers, just say that upfront.
>> 
>>  - Use of explicit refspec to fetch tags does not have much to do
>>    with turning "auto following" on or off.  It is a way to fetch
>>    tags that otherwise would not be fetched by auto-following.
>> 
>> Signed-off-by: Junio C Hamano <gitster@pobox.com>
>> ---
>>  Documentation/git-fetch.txt | 29 ++++++++++++++++-------------
>>  1 file changed, 16 insertions(+), 13 deletions(-)
>> 
>> diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt
>> index 5809aa4..d5f5b54 100644
>> --- a/Documentation/git-fetch.txt
>> +++ b/Documentation/git-fetch.txt
>> @@ -17,20 +17,23 @@ SYNOPSIS
>>  
>>  DESCRIPTION
>>  -----------
>> -Fetches named heads or tags from one or more other repositories,
>> -along with the objects necessary to complete them.
>> -
>> -The ref names and their object names of fetched refs are stored
>> -in `.git/FETCH_HEAD`.  This information is left for a later merge
>> -operation done by 'git merge'.
>> -
>> -By default, tags are auto-followed.  This means that when fetching
>> -from a remote, any tags on the remote that point to objects that exist
>> -in the local repository are fetched.  The effect is to fetch tags that
>> +Fetch branches and/or tags (collectively, "refs") from one or more
>> +other repositories, along with the objects necessary to complete the
>> +histories of them.
>
> Phrasing: s/the histories of them/their histories/

Yeah, thanks.

>> +
>> +The names of refs that are fetched, together with the object names
>> +they point at, are written to `.git/FETCH_HEAD`.  This information
>> +is used by a later merge operation done by 'git merge'.  In addition,
>
> Isn't this merge stuff about pull, not fetch?

It is true that "git pull" uses "git fetch" and .git/FETCH_HEAD is a
documented mechanism between the two to communicate what commits the
latter downloaded are to be merged by the former, and that is one of
the reasons why we had the description here in the original before
this patch.  A user can also do this to refer to the tip of the
single branch she fetched:

	git fetch origin master
        git log -p ..FETCH_HEAD
        git merge FETCH_HEAD

Perhaps "is used ... by 'git merge'" can be rephrased somehow, like
"can be used to refer to what was fetched"?  Or we could go in the
opposite direction and be more explicit, i.e.

	"git pull" calls "git fetch" internally, and this
	information is used by the former to learn what commits were
	fetched by the latter.

I dunno.

>> +the remote-tracking branches may be updated (see description on
>> +<refspec> below for details).
>
> I realize that "may be updated" is strictly correct, in that if the remote's
> branches have not changed since the last fetch then the local tracking
> branches won't change.
>
> But it took me a second or two to think of that.  The "may" kindof tripped me
> up.  The fact is that the local tracking branches are always updated to match
> the remote's branches, it's just that sometimes the remote's branches don't
> change.  So I think it would be clearer to say
>
> 	the remote-tracking branches are updated
>
> because this makes it clear that the command always makes your local tracking
> branches match the remote's.

The primary reason behind my "may be" was not "they may not have
done anything in the meantime", but was "we may not have configured
to track at all", but in that case by definition we don't have "the
remote-tracking branches", so now I realize that it is pointless to
say "may be updated".