From 29d55538b78fa8d916b99aef9a4b1e376df2dac0 Mon Sep 17 00:00:00 2001
From: Daniele Segato <daniele.segato@gmail.com>
Date: Fri, 26 Jul 2013 15:06:02 -0400
Subject: [PATCH] docs/git-tag: explain lightweight versus annotated tags

Stress the difference between the two with a suggestion on
when the user should use one in place of the other.

Signed-off-by: Daniele Segato <daniele.segato@gmail.com>
Signed-off-by: Jeff King <peff@peff.net>
Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-tag.txt | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 6470cffd32..6d01e6f77b 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -42,6 +42,17 @@ committer identity for the current user is used to find the
 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
 -------
-- 
2.40.0