From: Junio C Hamano <gitster@pobox.com>
Date: Wed, 31 Jul 2013 19:38:21 +0000 (-0700)
Subject: Merge branch 'ds/doc-two-kinds-of-tags'
X-Git-Tag: v1.8.4-rc1~11
X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/652d2bfa83e92d871eb034e13fd811fbd402c3f1?hp=-c

Merge branch 'ds/doc-two-kinds-of-tags'

* ds/doc-two-kinds-of-tags:
docs/git-tag: explain lightweight versus annotated tags
---

652d2bfa83e92d871eb034e13fd811fbd402c3f1
diff --combined Documentation/git-tag.txt
index 22894cbee6,6d01e6f77b..c418c44d40
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@@ -33,7 -33,7 +33,7 @@@ in the tag message
  If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <key-id>`
  are absent, `-a` is implied.
  
 -Otherwise just a tag reference for the SHA1 object name of the commit object is
 +Otherwise just a tag reference for the SHA-1 object name of the commit object is
  created (i.e. a lightweight tag).
  
  A GnuPG signed tag object will be created when `-s` or `-u
@@@ -42,6 -42,17 +42,17 @@@ committer identity for the current use
  GnuPG key for signing. 	The configuration variable `gpg.program`
  is used to specify custom GnuPG binary.
  
+ Tag objects (created with `-a`, `s`, or `-u`) are called "annotated"
+ tags; they contain a creation date, the tagger name and e-mail, a
+ tagging message, and an optional GnuPG signature. Whereas a
+ "lightweight" tag is simply a name for an object (usually a commit
+ object).
+ 
+ Annotated tags are meant for release while lightweight tags are meant
+ for private or temporary object labels. For this reason, some git
+ commands for naming objects (like `git describe`) will ignore
+ lightweight tags by default.
+ 
  
  OPTIONS
  -------
@@@ -126,12 -137,6 +137,12 @@@ This option is only applicable when lis
  	linkgit:git-check-ref-format[1].  Some of these checks
  	may restrict the characters allowed in a tag name.
  
 +<commit>::
 +<object>::
 +	The object that the new tag will refer to, usually a commit.
 +	Defaults to HEAD.
 +
 +
  CONFIGURATION
  -------------
  By default, 'git tag' in sign-with-default mode (-s) will use your
@@@ -248,7 -253,7 +259,7 @@@ $ git pull git://git..../proj.git maste
  In such a case, you do not want to automatically follow the other
  person's tags.
  
 -One important aspect of git is its distributed nature, which
 +One important aspect of Git is its distributed nature, which
  largely means there is no inherent "upstream" or
  "downstream" in the system.  On the face of it, the above
  example might seem to indicate that the tag namespace is owned