Re: [PATCH] Clarify that '--tags' fetches tags only

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 22, 2011, 04:28 UTC
Message-ID: <7vfwjpyzds.fsf@alter.siamese.dyndns.org>
In-Reply-To: <CAMOZ1BtPJ_Ddxo1UG2cxJMnGv9y8sR0rAyk3d_5JEz4kLsUQJQ@mail.gmail.com>

Michael Witten <mfwitten@gmail.com> writes:

Show 17 quoted lines

> On Thu, Sep 22, 2011 at 03:13, Andrew Ardill <andrew.ardill@gmail.com> wrote:
>>
>> Maybe:
>>
>> Note that if this option is specified, then only tags
>> are fetched. No other refs, such as a remote tracking
>> branch, will be updated, even if it has been updated
>> on the remote end.
>>
>> extra info on how this option is merely a short-hand for writing the
>> refspec `refs/tags/*:refs/tags/* could go here
>
> Junio just explained why your description is inadequate and confusing.
> ...
> If I were a newbie and were to read the text that I just proferred as
> a clarification of --tags, then I would next look up just WTF a
> refspec is, and then a branch, and then...

I do agree with you that it is a futile exercise to sweep fundamental concepts under the rug, fearing that they are too detailed and too hard for the casual readers. By understanding how simple the fundamental concepts and rules are, readers can have a coherent and clear mental model of the world and synthesize these fundamental rules to understand more complex operations the Porcelain commands offer to help every day tasks.

I however do not think, and I certainly did not mean, that the description of "--tags" option is necessarily the place we should bombard a new user with the term refspec and "refs/tags/*:refs/tags/*" syntax.

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.

If the logic flow of the document presents the list of options before helping the readers understand the above basic facts and rules, then I think _that_ is the problem with the document we need to be addressing, not the description of an individual option such as "--tags".