From: Junio C Hamano <gitster@pobox.com>
Date: Thu, 22 Sep 2011 00:49:14 GMT
Subject: Re: [PATCH] Clarify that '--tags' fetches tags only
Message-ID: <7vwrd1z9it.fsf@alter.siamese.dyndns.org>
In-Reply-To: <CAMOZ1BuSd52woX0utOQ84gbCzBkZg3ATKnE+7G_BrD5_hUQSiQ@mail.gmail.com>

Michael Witten <mfwitten@gmail.com> writes:

> On Wed, Sep 21, 2011 at 23:52, Anatol Pomozov <anatol.pomozov@gmail.com> wrote:
>> +       linkgit:git-config[1]. Note that if this option is specified
>> +       then only tags are fetched, refs under refs/heads/* stay unchanged.
>
> Note that if this option is specified, then only tags
> are fetched; refs under refs/heads/* are not changed.

Can we improve the wording without singling out refs/heads/* specifically?

I think the updated wording is not desirable for two reasons.

For one thing, for the most newbies, I think refs/remotes/origin/* (not
refs/heads/*) would be the hierarchy that they may expect to get updated
and surprised.

When you give --tags (or any other refspec for that matter; --tags is
merely a short-hand for "refs/tags/*:refs/tags/*") explicitly from the
command line, you are overriding the refspecs configured for the remote,
and all the refs that are _not_ covered by the refspec you gave from the
command line will stay unchanged, not just refs/heads/* but refs under
other hierarchies (like refs/remotes/* and refs/notes/*). 

Once the reader understands that the command line _overrides_ the
configured fetch refspecs, everything else should fall naturally into
place without further explanation.  For example,

	$ git pull origin frotz

would internally invoke "git fetch origin another_branch", and it would
not update any refs for the _same exact reason_ [*1*].  You are giving a
refspec from the command line (in this case, "grab refs/heads/frotz, but
do not store it anywhere"), and it overrides the usual fetch refspec that
may update "+refs/heads/*:refs/remotes/origin/*" (grab all refs at the
origin under refs/heads/ hierarchy, and store in refs/remotes/origin).


[Footnote]

*1* The merging of the result would update the current branch but that is
a natural consequence of "a pull integrates by running either a merge or a
rebase after running a fetch".