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

From: Michael Witten <mfwitten@gmail.com>
Date: Sep 22, 2011, 03:24 UTC
Message-ID: <CAMOZ1BtPJ_Ddxo1UG2cxJMnGv9y8sR0rAyk3d_5JEz4kLsUQJQ@mail.gmail.com>
In-Reply-To: <CAH5451nb=DTed2kAVNQmFBbGFJ9zvQAtBE+VCzKqZfGMgYpx5w@mail.gmail.com>

On Thu, Sep 22, 2011 at 03:13, Andrew Ardill <andrew.ardill@gmail.com> wrote:

Show 71 quoted lines

> On 22 September 2011 12:07, Michael Witten <mfwitten@gmail.com> wrote:
>> On Thu, Sep 22, 2011 at 02:01, Michael Witten <mfwitten@gmail.com> wrote:
>>> On Thu, Sep 22, 2011 at 00:49, Junio C Hamano <gitster@pobox.com> wrote:
>>>> --tags is merely a short-hand for "refs/tags/*:refs/tags/*")
>>>> explicitly from the command line
>>>
>>> [Disclaimer: I don't know the code or the semantics]
>>>
>>> Why not just use that explanation?
>>>
>>>  This option is merely a short-hand for writing
>>>  the refspec `refs/tags/*:refs/tags/*'; consequently,
>>>  using this option overrides any default refspec that
>>>  would be used if no refspec were provided on the
>>>  command line. That is,
>>>
>>>    git fetch --tags origin frotz
>>>
>>>  is equivalent to:
>>>
>>>    git fetch origin frotz 'refs/tags/*:refs/tags/*'
>>>
>>> In fact, if the command line parsing performed by `git fetch'
>>> is reasonably intelligent, then it might be worthwhile
>>> to relocate `--tags' in the example:
>>>
>>>  That is,
>>>
>>>    git fetch origin frotz --tags
>>>
>>>  is equivalent to:
>>>
>>>    git fetch origin frotz 'refs/tags/*:refs/tags/*'
>>>
>>
>> Maybe this is less confusing for the example:
>>
>>  That is,
>>
>>    git fetch origin --tags
>>    git fetch origin frotz --tags bar
>>
>>  are equivalent to:
>>
>>    git fetch origin 'refs/tags/*:refs/tags/*'
>>    git fetch origin frotz 'refs/tags/*:refs/tags/*' bar
>
> This will only help people who understand that tags are just refs
> stored in refs/tags, and who understand the 'ref:ref' syntax. I think
> it is a good example to have, but people can understand the process
> and results of 'pulling/fetching a tag' without necessarily needing to
> know that tags are stored somewhere, or knowing the exact fetch
> mechanism. If these need to be documented, it should be in the
> appropriate place (which I don't think is here).
>
> I think we are skirting around the real issue, and that is that
> pulling tags will often grab objects that are *meant* to be on a
> remote branch (from the user's perspective) but that appear to be
> hanging because the remote branch ref was not updated at the same
> time. Perhaps an example or explanation of why this is the case would
> be more useful?
>
> 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.

There's so much confusion around git exactly because people are always trying to hide just WTF is going on (especially by using TERRIBLE terms like `branch'; see my numerous discussions).

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...

You see? That's exactly how it should work. People should be given descriptions that arm them with the terms necessary to look up more information. We need to stop writing documentation for that hypothetical idiot who doesn't know his ass from his own face. We need to cater to those people who intend to read documentation for the purpose of understanding the system---not for the purpose of gettin' shit dun with any half-baked notion that is good enough for the most simplistic situation.

I'm sending in a patch presently.