From: Michael Witten Date: Thu, 22 Sep 2011 17:35:02 GMT Subject: Re: [PATCH v3] Docs: Clarify the --tags option of `git fetch' Message-ID: In-Reply-To: <7v1uv8zen5.fsf@alter.siamese.dyndns.org> On Thu, Sep 22, 2011 at 17:10, Junio C Hamano wrote: > Michael Witten writes: > >> 8<-----------8<-----------8<-----------8<-----------8<-----------8<----------- >> >> See the discussion starting here: >> >>   [PATCH] Clarify that '--tags' fetches tags only >>   Message-ID: <1314997486-29996-1-git-send-email-anatol.pomozov@gmail.com> >>   http://thread.gmane.org/gmane.comp.version-control.git/180636 > > It is a good practice to point to earlier discussions while polishing > patch, and it also is good to include pointers in the commit log message > as a supporting material (additional reading), but that is _NOT_ a > substitute for a properly written commit log message. You need to state > what problem you are trying to fix and how the proposed patch fixes it. > >>  Documentation/fetch-options.txt |   31 +++++++++++++++++++++++-------- >>  1 files changed, 23 insertions(+), 8 deletions(-) >> >> diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt >> index 39d326a..4cc5a80 100644 >> --- a/Documentation/fetch-options.txt >> +++ b/Documentation/fetch-options.txt >> @@ -56,14 +56,29 @@ endif::git-pull[] >>  ifndef::git-pull[] >>  -t:: >>  --tags:: >> -     Most of the tags are fetched automatically as branch >> -     heads are downloaded, but tags that do not point at >> -     objects reachable from the branch heads that are being >> -     tracked will not be fetched by this mechanism.  This >> -     flag lets all tags and their associated objects be >> -     downloaded. The default behavior for a remote may be >> -     specified with the remote..tagopt setting. See >> -     linkgit:git-config[1]. >> +     Most of a remote's tags are fetched automatically as branches are >> +     downloaded. However, git does not automatically fetch any tag that, >> +     when 'git fetch' completes, would not be reachable from any local >> +     branch head.  This option tells git to fetch all tags (and their >> +     associated objects). > > I would suggest clarifying the beginning of "git fetch --help" like the > attached patch. With that knowledge at hand, the readers do not need the > fuzzy "Most of ... are fetched" (leaving them wondering "what about the > rest, and how that Most is determined?"); we only need to say something > like "fetch all the tags from the remote and store them locally". > >  Documentation/git-fetch.txt |   21 ++++++++++----------- >  1 files changed, 10 insertions(+), 11 deletions(-) > > diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt > index 60ac8d2..c6c7236 100644 > --- a/Documentation/git-fetch.txt > +++ b/Documentation/git-fetch.txt > @@ -19,20 +19,19 @@ SYNOPSIS > >  DESCRIPTION >  ----------- > -Fetches named heads or tags from one or more other repositories, > -along with the objects necessary to complete them. > +Fetches branches and tags (collectively known as 'refs') from one or more > +other repositories, along with the objects necessary to complete them. > +Which refs are fetched are determined by the arguments, if > +given. Otherwise the default configured for the > +are used (see "REMOTES" section below for how works). > > -The ref names and their object names of fetched refs are stored > -in `.git/FETCH_HEAD`.  This information is left for a later merge > -operation done by 'git merge'. > +The ref names and their object names are also stored in `.git/FETCH_HEAD`. > +This information is used by 'git pull' that invokes this command. > >  When stores the fetched result in remote-tracking branches, > -the tags that point at these branches are automatically > -followed.  This is done by first fetching from the remote using > -the given s, and if the repository has objects that are > -pointed by remote tags that it does not yet have, then fetch > -those missing tags.  If the other end has tags that point at > -branches you are not interested in, you will not get them. > +the tags that point at commits on these branches are also fetched. Tags > +at the remote that point at commits that are not on these remote-tracking > +branches are not fetched by this mechanism (use `--tags` option to fetch them). > >  'git fetch' can fetch from either a single named repository, >  or from several repositories at once if is given and > The only problem is that none of what you say seems to be true. * The glossary very distinctly differentiates the term `branch' from `branch head'. * From skimming the code, it would seem that remote-tracking branch [*heads*] are not at all the determining factor for whether tags are automatically fetched. Rather, the determining factor is much more relaxed: Tags are fetched when a refspec's field is non-empty; it just so happens that a is usually non-empty because at least one remote-tracking branch [*head*] is being updated, but keep in mind that the branch being updated need not be considered a remote-tracking branch.