Re: [PATCH v3] Docs: Clarify the --tags option of `git fetch'

[Michael Witten <mfwitten@gmail.com>]

On Thu, Sep 22, 2011 at 17:10, Junio C Hamano <gitster@pobox.com> wrote:
> Michael Witten <mfwitten@gmail.com> 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.<name>.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 <refspec> arguments, if
> +given. Otherwise the default <refspec> configured for the <repository>
> +are used (see "REMOTES" section below for how <refspec> 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 <refspec> 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 <refspec>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 <group> 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 <dst> field is non-empty; it just so
    happens that a <dst> 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.