git fetch --tags doesn't quite do what I expect

I've been doing some updating on my git scripts to make use of the features that you have been working hard to put in (thank you). My script to update my local "linus" branch from Linus' master branch at kernel.org had a simple "git fetch linus" (with the appropriate[1] URL and Pull lines in .git/refs/remotes/linus) followed by an unholy piece of script that parsed the output from "git-ls-remote --tags linus" to see if I had all the latest tags, and get them if I didn't.

Looking at the manual, I thought that I could just change the "git
fetch linus" to
be "git fetch --tags linus" and drop the script.  But it appears that
with the "--tags"
argument the "fetch" will not fetch anything beyond the tagged commits (i.e.
at the moment v2.6.15-rc1) ... so I need both:
      git fetch --tags linus
and
      git fetch linus

one to get any new tags, and the other to fetch all the way up to "master".

Is this intended behaivour? If so, the "--tags" entry on the git-fetch(1) man page needs a little extra text to say that --tags limits the fetch to only commits reachable from the tags.

-Tony

[1] Contents:
URL: master.kernel.org:/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
Pull: master:linus

Tony Luck <tony.luck@gmail.com> writes:

I think both Linus (who did the initial implementation of "git fetch --tags") and I are in "tags do not matter until you care" camp, and the expected usage pattern is that you frequently do "git fetch" or "git pull", but "git fetch --tags" is done only every once in a while, just to give you known anchors to compare against or specify a known bottom for log, whatchanged and friends. The branch heads are necessary for your day to day work, the tags are less essential. That is what I mean by "tags do not matter until you care".

A tag usually points at somewhere in the commit chain leading to branch heads [*1*], and if your branch heads are up to date, "git fetch --tags" does not download anything other than the tags themselves, finds the commits they point at are already available and complete, and stops there.

Now it happens that "git fetch --tags" slurps commits you do not yet have _if_ your branch heads are behind, because git barebone Porcelain is designed to keep your object database complete (i.e. it does not just fetch and store tags under refs/tags/ without making sure you have everything they connect to). What you saw that is a side effect of the above design assumption.

I am not good at documenting things, so I'd appreciate if somebody paraphrased the above and send it back to me in a patch form to update the document ;-).

[Footnote]

*1* This is not necessarily true; tags can point at anything, and indeed v1.0rc3 tag point at another tag and junio-gpg-tag points at a freestanding blob. Even a tag pointing at a commit, as Daniel suggested in

	<Pine.LNX.4.64.0511041745480.25300@iabervon.org>

I could do the "pu" branch as a tag without exposing the actual branch. Then that tag would point at a chain of commits not connected to any branch head.

On Fri, Nov 18, 2005 at 12:06:29PM -0800, Junio C Hamano wrote:

How about this:

[PATCH] Update pull/fetch --tags documentation

When fetching/pulling from a remote repository the "--tags" option can be used to pull tags too. Document that it will limit the pull to only commits reachable from the tags.

Signed-off-by: Tony Luck <tony.luck@intel.com>

---