From: Michael Witten <mfwitten@gmail.com>
To: Junio C Hamano <gitster@pobox.com>
Cc: Anatol Pomozov <anatol.pomozov@gmail.com>,
Drew Northup <drew.northup@maine.edu>,
Andrew Ardill <andrew.ardill@gmail.com>,
Daniel Johnson <computerdruid@gmail.com>,
git@vger.kernel.org
Subject: Re: [PATCH v3] Docs: Clarify the --tags option of `git fetch'
Date: Thu, 22 Sep 2011 17:38:00 +0000 [thread overview]
Message-ID: <CAMOZ1BtHUtZvQJMM0yhOumb8aq7NnHv8udPOVdciQE3=jNGq4Q@mail.gmail.com> (raw)
In-Reply-To: <CAMOZ1BtBEHae7x-cn=DtnzwoyC_sYedgFmyNwrDuju+kcJU4hg@mail.gmail.com>
On Thu, Sep 22, 2011 at 17:35, Michael Witten <mfwitten@gmail.com> wrote:
> 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.
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*].
next prev parent reply other threads:[~2011-09-22 17:38 UTC|newest]
Thread overview: 32+ messages / expand[flat|nested] mbox.gz Atom feed top
2011-09-02 21:04 [PATCH] Clarify that '--tags' fetches tags only Anatol Pomozov
2011-09-02 21:18 ` Drew Northup
2011-09-21 23:52 ` Anatol Pomozov
2011-09-22 0:13 ` Michael Witten
2011-09-22 0:49 ` Junio C Hamano
2011-09-22 2:01 ` Michael Witten
2011-09-22 2:07 ` Michael Witten
2011-09-22 3:13 ` Andrew Ardill
2011-09-22 3:24 ` Michael Witten
2011-09-22 3:39 ` [PATCH] Docs: Clarify the --tags option of `git fetch' Michael Witten
2011-09-22 3:48 ` Michael Witten
2011-09-22 4:28 ` [PATCH] Clarify that '--tags' fetches tags only Junio C Hamano
2011-09-22 7:23 ` [PATCH v3] Docs: Clarify the --tags option of `git fetch' Michael Witten
2011-09-22 17:10 ` Junio C Hamano
2011-09-22 17:35 ` Michael Witten
2011-09-22 17:38 ` Michael Witten [this message]
2011-09-22 4:00 ` [PATCH] Clarify that '--tags' fetches tags only Junio C Hamano
2011-09-22 4:17 ` [PATCH v2] Docs: Clarify the --tags option of `git fetch' Michael Witten
2011-09-22 1:14 ` [PATCH] Clarify that '--tags' fetches tags only Daniel Johnson
2011-09-30 2:51 ` Peter Shenkin
2011-09-30 8:44 ` Jakub Narebski
2011-09-30 13:23 ` Michael Witten
2011-10-01 5:40 ` Peter Shenkin
2011-10-01 14:11 ` Michael Witten
2011-10-01 17:16 ` Peter Shenkin
2011-10-01 18:45 ` Michael Witten
2011-10-01 20:22 ` Peter Shenkin
2011-10-01 20:56 ` Michael Witten
2011-10-01 21:41 ` Peter Shenkin
2011-10-01 22:06 ` Peter Shenkin
2011-09-30 18:37 ` Junio C Hamano
2011-10-01 5:51 ` Peter Shenkin
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to='CAMOZ1BtHUtZvQJMM0yhOumb8aq7NnHv8udPOVdciQE3=jNGq4Q@mail.gmail.com' \
--to=mfwitten@gmail.com \
--cc=anatol.pomozov@gmail.com \
--cc=andrew.ardill@gmail.com \
--cc=computerdruid@gmail.com \
--cc=drew.northup@maine.edu \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).