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

[Michael Witten <mfwitten@gmail.com>]

On Wed, 21 Sep 2011 21:28:15 -0700, Junio C Hamano wrote:

> I expect the readers to, and I hope the documentation to help them to,
> understand the following three basic facts and rules before diving into
> descriptions of individual options, such as the paragraph we are
> discussing:
>
>  * "git fetch" command serves two purposes:
>
>    (1) It transfers objects the repository the command is invoked in does
>    not have from the remote repository. The objects transferred are the
>    commits that are necessary to complete the ancestry chain of _some_
>    history, and data (i.e. trees and blobs) associated to use these
>    commits.
>
>    (2) It optionally can update the local refs (e.g. branches and tags)
>    with copies of the refs taken from the remote repository.
>
>  * In the above, the user needs to tell the command two things. One is
>    "where the remote repository is". The other is "what refs to fetch and
>    (optionally) how to store them". The latter "what to fetch" also
>    determines what that "_some_ history" above is (i.e. everything
>    reachable from the refs that are fetched).
>
>  * "What to fetch and how to store" have a default, recorded in the
>    repository configuration file, that is used when the user does not give
>    that information to the command from the command line. If the user does
>    give that information from the command line, that default is not used
>    at all. IOW, the command line overrides the default.
>
> With that understanding, the _only_ thing that "--tags" description needs
> to talk about is that it is an explicit way to give that "what to fetch
> and how to store" information from the command line. It instructs the
> command to fetch all the tags from the remote repository and store them
> locally.

For at least the near term, this patch may do a pretty good job of
achieving those goals without having to change too much; I do some
careful maneuvering to avoid mentioning refspecs until quite late
in the description.

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

Suggested-by: Anatol Pomozov <anatol.pomozov@gmail.com>
Signed-off-by: Michael Witten <mfwitten@gmail.com>
---
 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).
++
+The 'git fetch' command is often supplied with a default set of branch
+heads to fetch, but using this option tells 'git fetch' to ignore those
+defaults.
++
+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/*'
++
+The default behavior for a remote may be specified with
+the remote.<name>.tagopt setting. See linkgit:git-config[1].
 
 --recurse-submodules[=yes|on-demand|no]::
 	This option controls if and under what conditions new commits of
-- 
1.7.6.409.ge7a85