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

On Thu, Sep 22, 2011 at 03:13, Andrew Ardill [off-list ref] wrote:

On 22 September 2011 12:07, Michael Witten [off-list ref] wrote:

quoted

On Thu, Sep 22, 2011 at 02:01, Michael Witten [off-list ref] wrote:

quoted

On Thu, Sep 22, 2011 at 00:49, Junio C Hamano [off-list ref] wrote:

quoted

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