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

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

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


Regards,
Andrew