Re: [PATCH] Clarify that '--tags' fetches tags only

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 22, 2011, 00:49 UTC
Message-ID: <7vwrd1z9it.fsf@alter.siamese.dyndns.org>
In-Reply-To: <CAMOZ1BuSd52woX0utOQ84gbCzBkZg3ATKnE+7G_BrD5_hUQSiQ@mail.gmail.com>

Michael Witten <mfwitten@gmail.com> writes:

Show 6 quoted lines

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