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

Michael Witten [off-list ref] writes:

On Wed, Sep 21, 2011 at 23:52, Anatol Pomozov [off-list ref] wrote:

quoted

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