From: Michael Witten Date: Thu, 22 Sep 2011 17:38:00 GMT Subject: Re: [PATCH v3] Docs: Clarify the --tags option of `git fetch' Message-ID: In-Reply-To: On Thu, Sep 22, 2011 at 17:35, Michael Witten wrote: > 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. DAMNIT That last bit should use the world `head': but keep in mind that the branch *head* being updated need not be considered a remote-tracking branch [*head*].