On 07/25/2013 04:47 PM, Marc Branchaud wrote:
On 13-07-25 09:45 AM, Daniele Segato wrote:
From d0f4eca712e7cf74286bfab306763a8a571b6c95 Mon Sep 17 00:00:00 2001
From: Daniele Segato <daniele.segato@xxxxxxxxx>
Date: Thu, 25 Jul 2013 15:33:18 +0200
Subject: [PATCH] git-tag man: when to use lightweight or annotated tags
stress the difference between the two with suggestion on when the user
should use one in place of the other.
Signed-off-by: Daniele Segato <daniele.segato@xxxxxxxxx>
---
Documentation/git-tag.txt | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 22894cb..48f5504 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -36,6 +36,10 @@ are absent, `-a` is implied.
Otherwise just a tag reference for the SHA-1 object name of the commit
object is
created (i.e. a lightweight tag).
+Annotated and Lightweight tags are not the same thing for git and you shouldn't
+mix them up. Annotated tags are meant for release while lightweight tags are
+meant to tag random commits.
Unfortunately the word "annotated" hasn't yet been introduced at this point,
so the overall effect is even more confusing.
Actually annotated tag has already be introduced but they haven't been
named "Annotated" yet; what about changing the above paragraph like this:
If one of `-a`, `-s`, or `-u <key-id>` is passed, the command
-creates a 'tag' object, and requires a tag message. Unless
+creates a 'tag' object called 'Annotated tag', and requires a tag
message. Unless
`-m <msg>` or `-F <file>` is given, an editor is started for the user
to type
in the tag message.
Also, I find the "release" vs.
"random" distinction a bit misleading since both types of tag can refer to
any object.
I can change it into something like these (using your suggestion below):
"Annotated tags are meant for release while lightweight tags are meant
for private or temporary object labels."
What do you think?
I also liked the direction of your earlier "command only
consider annotated tags by default" phrasing.
I also think it would be helpful. We can write this after the previous
sentence:
"Most git commands only consider Annotated tags by default."
After reading the Tagging section of the Git Book[1] I came up with the
following. Feel free to modify it as you like, or ignore it completely:
Tag objects (created with -a) are called annotated tags. While a lightweight
tag is simply a name for an object (usually a commit object), an annotated
tag contains the creation date, the tagger's name and e-mail, a tagging
message, and can be signed and verified with GNU Privacy Guard (GnuPG). Most
git commands only consider annotated tags by default. In general lightweight
tags are for private or temporary object labels, while annotated tags are
meant to be permanent and/or published. For example, an annotated tag is
normally used to identify a release point.
M.
[1] http://git-scm.com/book/en/Git-Basics-Tagging
I took some inspiration but I think writing about what a tag object
contains in the documentation is not useful at that point in the doc.
What's important there is that user do understand the difference between
Annotated and Lightweight tags.
I'll follow with a patch containing these modification I'm talking
about, should be easier to comment.
Regards,
Daniele
--
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