On Wed, 21 Sep 2011 21:28:15 -0700, Junio C Hamano wrote: > 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. For at least the near term, this patch may do a pretty good job of achieving those goals without having to change too much; I do some careful maneuvering to avoid mentioning refspecs until quite late in the description. 8<-----------8<-----------8<-----------8<-----------8<-----------8<----------- See the discussion starting here: [PATCH] Clarify that '--tags' fetches tags only Message-ID: <1314997486-29996-1-git-send-email-anatol.pomozov@xxxxxxxxx> http://thread.gmane.org/gmane.comp.version-control.git/180636 Suggested-by: Anatol Pomozov <anatol.pomozov@xxxxxxxxx> Signed-off-by: Michael Witten <mfwitten@xxxxxxxxx> --- Documentation/fetch-options.txt | 31 +++++++++++++++++++++++-------- 1 files changed, 23 insertions(+), 8 deletions(-) diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 39d326a..4cc5a80 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -56,14 +56,29 @@ endif::git-pull[] ifndef::git-pull[] -t:: --tags:: - Most of the tags are fetched automatically as branch - heads are downloaded, but tags that do not point at - objects reachable from the branch heads that are being - tracked will not be fetched by this mechanism. This - flag lets all tags and their associated objects be - downloaded. The default behavior for a remote may be - specified with the remote.<name>.tagopt setting. See - linkgit:git-config[1]. + Most of a remote's tags are fetched automatically as branches are + downloaded. However, git does not automatically fetch any tag that, + when 'git fetch' completes, would not be reachable from any local + branch head. This option tells git to fetch all tags (and their + associated objects). ++ +The 'git fetch' command is often supplied with a default set of branch +heads to fetch, but using this option tells 'git fetch' to ignore those +defaults. ++ +This option is merely a shorthand for writing the refspec +`refs/tags/\*:refs/tags/\*'; that is, ++ + git fetch origin --tags + git fetch origin --tags frotz ++ +are equivalent to: ++ + git fetch origin 'refs/tags/*:refs/tags/*' + git fetch origin frotz 'refs/tags/*:refs/tags/*' ++ +The default behavior for a remote may be specified with +the remote.<name>.tagopt setting. See linkgit:git-config[1]. --recurse-submodules[=yes|on-demand|no]:: This option controls if and under what conditions new commits of -- 1.7.6.409.ge7a85 -- 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