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

[Junio C Hamano <gitster@pobox.com>]

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