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

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

[Tony Luck]

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

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

[Junio C Hamano]

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

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

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.

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

[Luck, Tony]

On Fri, Nov 18, 2005 at 12:06:29PM -0800, Junio C Hamano wrote:
> 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 ;-).


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>

---

diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index 0e502ae..a25d04a 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -8,7 +8,9 @@
 -t, \--tags::
 	By default, the git core utilities will not fetch and store
 	tags under the same name as the remote repository;  ask it
-	to do so using `--tags`.
+	to do so using `--tags`.  Using this option will bound the
+	list of objects pulled to the remote tags.  Commits in branches
+	beyond the tags will be ignored.
 
 -u, \--update-head-ok::
 	By default `git-fetch` refuses to update the head which