On 22 September 2011 12:07, Michael Witten <mfwitten@xxxxxxxxx> wrote: > On Thu, Sep 22, 2011 at 02:01, Michael Witten <mfwitten@xxxxxxxxx> wrote: >> On Thu, Sep 22, 2011 at 00:49, Junio C Hamano <gitster@xxxxxxxxx> 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 Regards, Andrew -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html