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

---
 Documentation/fetch-options.txt |    3 ++-
 1 files changed, 2 insertions(+), 1 deletions(-)

diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index 39d326a..37d2316 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt

@@ -63,7 +63,8 @@ ifndef::git-pull[]
 	flag lets all tags and their associated objects be
 	downloaded. The default behavior for a remote may be
 	specified with the remote.<name>.tagopt setting. See
-	linkgit:git-config[1].
+	linkgit:git-config[1]. Note that if this option is specified
+	then only tags are fetched, refs under refs/heads/* stay unchanged.
 
 --recurse-submodules[=yes|on-demand|no]::
 	This option controls if and under what conditions new commits of

-- 
1.7.7.rc0.72.g4b5ea.dirty

On Fri, 2011-09-02 at 14:04 -0700, Anatol Pomozov wrote:

-	linkgit:git-config[1].
+	linkgit:git-config[1]. Note that if this option is specified
+	then only tags are fetched, refs under refs/heads/* stay unchanged.

Anatol,
Looks like a sane change to me. You might want to check
Documentation/SubmittingPatches in the git repository if you want Junio
to include your patch. It is probably also worth CC-ing those whom did
the previous work on that documentation and the tags code to make sure
your change is correct.

-- 
-Drew Northup
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

'git fetch --tags' fetches tags only and leaves heads untouched.
Many people are confused by the fact that 'git fetch --tags'
does not fetch heads.

Signed-off-by: Anatol Pomozov <redacted>
---
 Documentation/fetch-options.txt |    3 ++-
 1 files changed, 2 insertions(+), 1 deletions(-)

diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index 39d326a..37d2316 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt

@@ -63,7 +63,8 @@ ifndef::git-pull[]
 	flag lets all tags and their associated objects be
 	downloaded. The default behavior for a remote may be
 	specified with the remote.<name>.tagopt setting. See
-	linkgit:git-config[1].
+	linkgit:git-config[1]. Note that if this option is specified
+	then only tags are fetched, refs under refs/heads/* stay unchanged.
 
 --recurse-submodules[=yes|on-demand|no]::
 	This option controls if and under what conditions new commits of

-- 
1.7.7.rc0.72.g4b5ea.dirty

On Wed, Sep 21, 2011 at 23:52, Anatol Pomozov [off-list ref] 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.

On Wednesday, September 21, 2011 04:52:56 PM Anatol Pomozov wrote:

I like this clarification. It would be better placed before the note about the 
tagopt setting, as it clarifies the statement before that ("This flag lets all 
tags and their associated objects be downloaded.")

In fact, the optimal solution might be to rework that sentence with the 
clarification from yours, so something like "This flag lets all tags and their 
associated objects be downloaded instead of"...

Hi,

I just searched the List to see if there were any postings on
"fetch --tags", because I was recently  thrown for a loop by
the fact the this command retrieves only tags (and commits
needed to fulfill them). So I was very happy to find this
discussion. I was actually trying to figure out whether the
observed behavior is a bug, given that there is no mention of
it in the documentation.

Perhaps it will be useful to say what would have been most
helpful for me. In the current documentation for "fetch
--tags", one sentence reads, "This flag lets all tags and
their associated  objects be downloaded." The following small
modification would, IMO, be sufficient: "This flag causes all
tags and their associated objects (only) to be downloaded."

Now I have a related question. I always want to retrieve all
tags from tracking branches when I do a "git pull". Right now,
if I want to do this, it seem (unless I am missing something)
that I have to do "git fetch --tags; git fetch;  git merge". Is
there a way I can put something into my .git/config file so
that I get this effect simply by doing a "git pull"? That's
what I was trying to do when I added "tagopt = --tags".

Thanks,
-P.

Peter Shenkin [off-list ref] writes:

[...]

Now I have a related question. I always want to retrieve all
tags from tracking branches when I do a "git pull". Right now,
if I want to do this, it seem (unless I am missing something)
that I have to do "git fetch --tags; git fetch;  git merge". Is
there a way I can put something into my .git/config file so
that I get this effect simply by doing a "git pull"? That's
what I was trying to do when I added "tagopt = --tags".

Actually fetching of branches on remote into remote-tracking branches
would also fetch all tags that point to commits on fetched branches
(so called "autofollow" feature).

If you want to fetch _all_ tags, you need to configure fetched
branches (e.g. via glob refspec). I think that then "tagopt = --tags"
works as expected then, as it is in addition to refspec not as the
only refspec; "fetch = +refs/tags/*:refs/tags/*" should work as well.

HTH
-- 
Jakub Narębski

On Fri, Sep 30, 2011 at 02:51, Peter Shenkin [off-list ref] wrote:

Perhaps it will be useful to say what would have been most
helpful for me. In the current documentation for "fetch
--tags", one sentence reads, "This flag lets all tags and
their associated  objects be downloaded." The following small
modification would, IMO, be sufficient: "This flag causes all
tags and their associated objects (only) to be downloaded."

Well, you're missing the fact that it not only causes those to
be downloaded, but it also causes the defaults to be ignored,
which is why you don't get the other stuff. You can still tell
git to fetch anything else you want in addition.

See here:

  [PATCH v3] Docs: Clarify the --tags option of `git fetch'
  Message-ID: [off-list ref]
  http://article.gmane.org/gmane.comp.version-control.git/181887

Michael Witten <mfwitten <at> gmail.com> writes:

Well, you're missing the fact that it not only causes those to
be downloaded, but it also causes the defaults to be ignored,
which is why you don't get the other stuff. You can still tell
git to fetch anything else you want in addition.

I was no longer missing it at the time I posted. 

But that is indeed what I was missing when I first encountered 
the behavior. The purpose of posting was to point out that 
with  a very small change in the documentation,  I would not
have missed it. 

-P.

On Sat, Oct 1, 2011 at 05:40, Peter Shenkin [off-list ref] wrote:

Michael Witten <mfwitten <at> gmail.com> writes:

quoted

Well, you're missing the fact that it not only causes those to
be downloaded, but it also causes the defaults to be ignored,
which is why you don't get the other stuff. You can still tell
git to fetch anything else you want in addition.

I was no longer missing it at the time I posted.

But that is indeed what I was missing when I first encountered
the behavior. The purpose of posting was to point out that
with  a very small change in the documentation,  I would not
have missed it.

However, my point was this:

  You can still tell git to fetch anything else you want in addition.

That point doesn't seem clear with your proposed alteration.

Michael Witten <mfwitten <at> gmail.com> writes:

However, my point was this:

  You can still tell git to fetch anything else you want in addition.

Michael,

Yes, you are right. I am still missing how to do that.

Can you show me a sample fetch invocation that would
have the effect of downloading all tags and also branch heads?

Thanks,
-P.

On Sat, Oct 1, 2011 at 17:16, Peter Shenkin [off-list ref] wrote:

Michael Witten <mfwitten <at> gmail.com> writes:

quoted

However, my point was this:

  You can still tell git to fetch anything else you want in addition.

Michael,

Yes, you are right. I am still missing how to do that.

Can you show me a sample fetch invocation that would
have the effect of downloading all tags and also branch heads?

Unfortunately, there's currently no way to tell "git fetch" to
download whatever your configuration files specify as default, but you
can at least be explicit by using what's called a "refspec" (which is
documented in "git help fetch"):

  git fetch --tags origin '+refs/heads/*:refs/remotes/origin/*'

You could probably get your hands on the default refspec by rigging
something up with "git symbolic-ref" and "git config", but that's so
much hassle; currently, it is probably best just to run "git fetch"
twice.

Sincerely,
Michael Witten

You might also find this email insightful:

  http://article.gmane.org/gmane.comp.version-control.git/181911
  Message-ID: [off-list ref]
  Subject: Re: any way to "re-sync" a bare repository against
               another bare repository?

Michael Witten <mfwitten <at> gmail.com> writes:

  git fetch --tags origin '+refs/heads/*:refs/remotes/origin/*'

Well, Junio had just about convinced me that there was
nothing wrong with the documentation -- just with the
way I was reading it -- until I read the above.

I tried it and yes, it does do what I want. Which was not
at all my expectation, having read Junio's comment about
how the documentation is to be read.

Junio argued that the man-page mod I suggested -- 
namely, "This flag causes all tags and their associated
objects (only) to be downloaded." -- was unneeded 
because the meaning, though correct, is clear already and
therefore redundant.

But the real problem is that the reading he gives is just
wrong.

I have the following in my .git/config file:

[remote "origin"]
	fetch = +refs/heads/*:refs/remotes/origin/*
	tagopt = --tags
	url = <whatever>

Given this, I do not see how anyone could infer from 
anything in the documentation that

git fetch

would do anything different from:

git fetch --tags origin +refs/heads/*:refs/remotes/origin/*

If I am wrong about this, please cite chapter and verse.

The question is not how the --tags option should be
documented, but rather why "--tags" should behave
differently when the refspec is given on the commandline
than when the refspec is given in the .git/config file.

In fact, I no longer think it is a documentation error. It
is a just a really terrible implementation decision. If it
was desired to allow "git fetch --tags" to work without
using the user's specified refspec, then a "--no-heads"
option should have been provided to override the user's
refspec -- no matter where it was given.

Though a retrofit would likely break too many workflows,
the best one might hope for now would likely be the
addition of a "--heads" option, which would have the
effect of  bringing down the branch heads even though
this would not normally be done." 

But then it would still be necessary to say that "--tags"
does not normally obey the user's refspec if given in the
config file, but does if given on the command line. 

I might still be missing something. If anyone thinks the
current behavior is clear from a careful reading of the
documentation, I would like to hear how that inference
could be drawn. For no matter how one reads the --tags
description, it seems it is wrong in one of the two cases.

It is either wrong for a refspec on the command-line (if
you think it says it downloads tags only) or else it is wrong
for refspec in the config file (if you think it says it downloads
tags and heads).

On Sat, Oct 1, 2011 at 20:22, Peter Shenkin [off-list ref] wrote:

The question is not how the --tags option should be
documented, but rather why "--tags" should behave
differently when the refspec is given on the commandline
than when the refspec is given in the .git/config file.

Again, see here:

 [PATCH v3] Docs: Clarify the --tags option of `git fetch'
 Message-ID: [off-list ref]
 http://article.gmane.org/gmane.comp.version-control.git/181887

namely:

    This option is merely a shorthand for writing the refspec
    `refs/tags/\*:refs/tags/\*'; that is,

            git fetch origin --tags
            git fetch origin --tags frotz

    are equivalent to:

            git fetch origin 'refs/tags/*:refs/tags/*'
            git fetch origin frotz 'refs/tags/*:refs/tags/*'

In other words, by writing "--tags", you are actually writing
"refs/tags/\*:refs/tags/\*"; because you are stating an *explicit*
refspec, "git fetch" doesn't bother with any *implicit* default
in your config, which is consistent with how "git fetch" works.

It would probably be a good idea if there were a "--defaults", too.

Michael Witten <mfwitten <at> gmail.com> writes:
 

On Sat, Oct 1, 2011 at 20:22, Peter Shenkin <shenkin <at> gmail.com> wrote:
    [--tags] is merely a shorthand for writing the refspec
    `refs/tags/\*:refs/tags/\*'; that is,

Yes, I understand that fully and it makes perfect sense.

But it leaves unexplained and undocumented the fact
that the user's specification of an *additional* refspec is
observed if the additional refspec is given on the
command line but ignored if the additional refspec is
given in the config file.

-P.

Peter Shenkin <shenkin <at> gmail.com> writes:

But it leaves unexplained and undocumented the fact
that the user's specification of an *additional* refspec is
observed if the additional refspec is given on the
command line but ignored if the additional refspec is
given in the config file.

I have to take this back. It makes sense that a refspec on
the cmdline overrides one in the config file.

I understand the behavior now, and Michael's  suggestion of a
--default to add the refspec in the config file to the cmdline
is IMO a good one.

'Nuff said. (By me, anyway....)

Thanks for your help and patience, everyone.

-P.