Re: [PATCH] git-tag man: when to use lightweight or annotated tags
On 07/26/2013 11:13 PM, Marc Branchaud wrote: On 13-07-26 01:19 PM, Daniele Segato wrote: By the way which is your role in the community? Don't want to be rude, I just don't know who I'm talking about :) the documentation maintainer? I'm just a git user and (very) occasional contributor. There's not much structure to the git community. Anyone who wants git to change can post a patch (or patch series) to this list. The patch can touch any area of the code, and it's considered good manners to CC whoever last touched the part(s) of the code being patched. The patch is discussed and revised as needed, and eventually the patch thread's participants arrive at a consensus as to whether or not the patch should become a part of git. If the patch is accepted the git maintainer (Junio C. Hamano) shepherds the patch through git's release process. See this note: http://git-blame.blogspot.ca/p/a-note-from-maintainer.html for more about that and other aspects of the git development community. M. Thanks. That helps a bit in understanding how I fit into the ml! Cheers, Daniele Segato -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] git-tag man: when to use lightweight or annotated tags
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.seg...@gmail.com 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.seg...@gmail.com --- 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 majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] git-tag man: when to use lightweight or annotated tags
From 34fdcb56e5784699ffa327ebfcd2c5cd99b61d2d Mon Sep 17 00:00:00 2001 From: Daniele Segato daniele.seg...@gmail.com 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.seg...@gmail.com --- Documentation/git-tag.txt |7 ++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 22894cb..5c6284e 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -26,7 +26,7 @@ to delete, list or verify tags. Unless `-f` is given, the named tag must not yet exist. 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. @@ -36,6 +36,11 @@ 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 for private or temporary object labels. Most git commands only consider +Annotated tags by default. + A GnuPG signed tag object will be created when `-s` or `-u key-id` is used. When `-u key-id` is not used, the committer identity for the current user is used to find the -- 1.7.10.4 -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] git-tag man: when to use lightweight or annotated tags
On 13-07-26 04:46 AM, Daniele Segato wrote: From 34fdcb56e5784699ffa327ebfcd2c5cd99b61d2d Mon Sep 17 00:00:00 2001 From: Daniele Segato daniele.seg...@gmail.com Date: Thu, 25 Jul 2013 15:33:18 +0200 Subject: [PATCH] git-tag man: when to use lightweight or annotated tags When sending a patch to the list it's not necessary to include these headers, as the git tools will extract them from the email itself. Also, when sending a revision to a previously posted patch it's customary to include a revision number, e.g. [PATCHv2]. 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.seg...@gmail.com --- Documentation/git-tag.txt |7 ++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 22894cb..5c6284e 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -26,7 +26,7 @@ to delete, list or verify tags. Unless `-f` is given, the named tag must not yet exist. 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. 1) Don't capitalize annotated -- it's not capitalized anywhere else in the text. The same goes for lightweight. 2) I find the phrasing here awkward. The important thing to convey is that annotated tag is a synonym for tag object. The proposed text implies that there can be other kinds of tag objects that are not annotated tags, but I don't think that's true. I've mulled over different ways of introducing the annotated tag term here, but I can't come up with a succinct way to do it. I think it's better to just introduce the term later. Unless `-m msg` or `-F file` is given, an editor is started for the user to type in the tag message. @@ -36,6 +36,11 @@ 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 for private or temporary object labels. Most git commands only consider +Annotated tags by default. + I'm sorry, but I feel this misses the mark. It's redundant to say the tag types are not the same thing, since the fact that they have different names already implies that. Also, to me the admonition you shouldn't mix them up is just a scary warning that conveys no helpful information. Furthermore, I think simply stating that the tag types are meant for particular uses without explaining why is too glib. Although it may be natural in your circumstances to think of the tag types rigidly, I do not think that's true for all git users and I don't think the documentation should assume there's a One True Way to use tags. The text should give readers enough information to decide for themselves how they want to use the different types of tags. That's why I included the annotated tag's contents in my suggestion, so that readers could figure out which tag type best meets their needs. What you've proposed is a step in the right direction, but I think you need to go further. M. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] git-tag man: when to use lightweight or annotated tags
On 07/26/2013 04:51 PM, Marc Branchaud wrote: On 13-07-26 04:46 AM, Daniele Segato wrote: From 34fdcb56e5784699ffa327ebfcd2c5cd99b61d2d Mon Sep 17 00:00:00 2001 From: Daniele Segato daniele.seg...@gmail.com Date: Thu, 25 Jul 2013 15:33:18 +0200 Subject: [PATCH] git-tag man: when to use lightweight or annotated tags When sending a patch to the list it's not necessary to include these headers, as the git tools will extract them from the email itself. Also, when sending a revision to a previously posted patch it's customary to include a revision number, e.g. [PATCHv2]. Thanks, I'll try to do the right thing with the next patch. By the way which is your role in the community? Don't want to be rude, I just don't know who I'm talking about :) the documentation maintainer? Thanks for the help anyway. diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 22894cb..5c6284e 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -26,7 +26,7 @@ to delete, list or verify tags. Unless `-f` is given, the named tag must not yet exist. 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. 1) Don't capitalize annotated -- it's not capitalized anywhere else in the text. The same goes for lightweight. Ok 2) I find the phrasing here awkward. The important thing to convey is that annotated tag is a synonym for tag object. The proposed text implies that there can be other kinds of tag objects that are not annotated tags, but I don't think that's true. I've mulled over different ways of introducing the annotated tag term here, but I can't come up with a succinct way to do it. I think it's better to just introduce the term later. Ok, English is not my native language so no surprise it sound awkward ;) I'll follow your suggestion here and move everything later. Unless `-m msg` or `-F file` is given, an editor is started for the user to type in the tag message. @@ -36,6 +36,11 @@ 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 for private or temporary object labels. Most git commands only consider +Annotated tags by default. + I'm sorry, but I feel this misses the mark. It's redundant to say the tag types are not the same thing, since the fact that they have different names already implies that. Also, to me the admonition you shouldn't mix them up is just a scary warning that conveys no helpful information. Furthermore, I think simply stating that the tag types are meant for particular uses without explaining why is too glib. Although it may be natural in your circumstances to think of the tag types rigidly, I do not think that's true for all git users and I don't think the documentation should assume there's a One True Way to use tags. The text should give readers enough information to decide for themselves how they want to use the different types of tags. That's why I included the annotated tag's contents in my suggestion, so that readers could figure out which tag type best meets their needs. What you've proposed is a step in the right direction, but I think you need to go further. M. I tried to take into account everything you said to me and rewrite the patch, following this message. Regards, Daniele -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] git-tag man: when to use lightweight or annotated tags
On 13-07-26 01:19 PM, Daniele Segato wrote: By the way which is your role in the community? Don't want to be rude, I just don't know who I'm talking about :) the documentation maintainer? I'm just a git user and (very) occasional contributor. There's not much structure to the git community. Anyone who wants git to change can post a patch (or patch series) to this list. The patch can touch any area of the code, and it's considered good manners to CC whoever last touched the part(s) of the code being patched. The patch is discussed and revised as needed, and eventually the patch thread's participants arrive at a consensus as to whether or not the patch should become a part of git. If the patch is accepted the git maintainer (Junio C. Hamano) shepherds the patch through git's release process. See this note: http://git-blame.blogspot.ca/p/a-note-from-maintainer.html for more about that and other aspects of the git development community. M. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH] git-tag man: when to use lightweight or annotated tags
From d0f4eca712e7cf74286bfab306763a8a571b6c95 Mon Sep 17 00:00:00 2001 From: Daniele Segato daniele.seg...@gmail.com 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.seg...@gmail.com --- 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. + A GnuPG signed tag object will be created when `-s` or `-u key-id` is used. When `-u key-id` is not used, the committer identity for the current user is used to find the -- 1.7.10.4 -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] git-tag man: when to use lightweight or annotated tags
On 13-07-25 09:45 AM, Daniele Segato wrote: From d0f4eca712e7cf74286bfab306763a8a571b6c95 Mon Sep 17 00:00:00 2001 From: Daniele Segato daniele.seg...@gmail.com 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.seg...@gmail.com --- 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. Also, I find the release vs. random distinction a bit misleading since both types of tag can refer to any object. I also liked the direction of your earlier command only consider annotated tags by default phrasing. 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 -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
