git tag usability issue: Lightweight vs Annotated confusion for the end user (ex. git describe default)
Hi,
I think there is an issue with the documentation of git tag, or with the default being chosen for tags.
the git tag documentation say:
*****
If one of -a, -s, or -u <key-id> is passed, the command creates
a tag object, 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.
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 created (i.e. a lightweight tag).
******
And no options below is provided to list annotated tags only or lightweight tags only (is there a way to do so?)
I initially didn't get git cared too much on this difference: I've been using both annotated and lightweight tags without distinctions, annotated when I want to write something about the tag and non-annotated when I do not need it.
Since no option is given to show annotated only tags these made sense to me.
Recently I started using submodules and I noticed that:
git submodule status
sometimes gave me the tag name of the submodule between parentesis and sometimes it gave me something like this:
+6903774653de52d0206e0e6026ca6914def8a333 submodule (1.0-2-g6903774)
even if the 6903774653de52d0206e0e6026ca6914def8a333 was actually a tag (1.1)
the git help submodule say status use git describe, so I've entered the submodule directory and tried:
$ git describe 1.0-2-g6903774
$ git describe --tags 1.1
reading the git help describe I discovered the git describe made an assumption and default to just show annotated tags.
To me, this assumption should have been documented very clearly in the git tag help page, something 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 -m <msg> or -F <file> is given, an editor is started for the user to type 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 created (i.e. a lightweight tag).
ANNOTATED vs LIGHTWEIGHT tags
Some git command (ex. git describe) by default only consider
annotated tags. 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.
******
And I think an option in git tag to only show annotated tags (or only show lightweight tags) is needed.
Finally, now that I discovered this I can't replace the lightweights tags with annotated tags without a public announcement requiring all developers to delete their local tags.
I'm not aware of any discussion you did about this matter but I think there's something wrong here that should be fixed.
Regards,
Daniele Segato
Quoted 3 lines · Daniele Segato
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.
Nicely explained.
This is one of those "we who worked on Git (not worked "with" Git) for a long time _know_ it and do not need it to be explained, and we didn't spot that it is not explained in the documentation for new people."
Care to roll a documentation patch (and get a commit count for yourself ;-)?
Thanks.
PATCH 1/1 git-tag man: when to use lightweight or annotated tags
From d0f4eca712e7cf74286bfab306763a8a571b6c95 Mon Sep 17 00:00:00 2001
From: Daniele Segato <[email protected]>
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.
--- Documentation/git-tag.txt | 4 ++++ 1 file changed, 4 insertions(+)
Documentation/git-tag.txt +0 -0
@@ -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
Signature · 1 line
1.7.10.4
Re: [PATCH] git-tag man: when to use lightweight or annotated tags
Quoted 22 lines · Daniele Segato
From
d0f4eca712e7cf74286bfab306763a8a571b6c95Mon Sep 17 00:00:00 2001
From: Daniele Segato <[email protected]>
Date: Thu, 25 Jul 2013 15:33:18 +0200
Subject: [PATCH] git-tag man: when to use lightweight or annotated tagsstress the difference between the two with suggestion on when the user should use one in place of the other.
Signed-off-by Daniele Segato <[email protected]>--- Documentation/git-tag.txt | 4 ++++ 1 file changed, 4 insertions(+)Documentation/git-tag.txt +0
-0@@ -36,6 +36,10 @@ are absent, `-a` is implied. Otherwise just a tag reference for the SHA-1 object name of the commitobject is
created (i.e. a lightweight tag).
Documentation/git-tag.txt
Quoted 3 lines
Documentation/git-tag.txt +3
-0+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.
Re: [PATCH] git-tag man: when to use lightweight or annotated tags
Quoted 23 lines · Marc Branchaud
Quoted 22 lines · Daniele Segato
From
d0f4eca712e7cf74286bfab306763a8a571b6c95Mon Sep 17 00:00:00 2001
From: Daniele Segato <[email protected]>
Date: Thu, 25 Jul 2013 15:33:18 +0200
Subject: [PATCH] git-tag man: when to use lightweight or annotated tagsstress the difference between the two with suggestion on when the user should use one in place of the other.
Signed-off-by Daniele Segato <[email protected]>--- Documentation/git-tag.txt | 4 ++++ 1 file changed, 4 insertions(+)Documentation/git-tag.txt +0
-0@@ -36,6 +36,10 @@ are absent, `-a` is implied. Otherwise just a tag reference for the SHA-1 object name of the commitobject is
created (i.e. a lightweight tag).
Quoted 6 lines
Documentation/git-tag.txt
Quoted 3 lines
Documentation/git-tag.txt +3
-0+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.
Quoted 3 lines
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?
Quoted 2 lines
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."
Quoted 12 lines
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.
Quoted 4 lines
M.
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
Re: [PATCH] git-tag man: when to use lightweight or annotated tags
From 34fdcb56e5784699ffa327ebfcd2c5cd99b61d2d Mon Sep 17 00:00:00 2001
From: Daniele Segato <[email protected]>
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.
--- Documentation/git-tag.txt | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-)
Documentation/git-tag.txt +1 -1
@@ -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
Signature · 1 line
1.7.10.4
Re: [PATCH] git-tag man: when to use lightweight or annotated tags
Quoted 4 lines · Daniele Segato
From
34fdcb56e5784699ffa327ebfcd2c5cd99b61d2dMon Sep 17 00:00:00 2001
From: Daniele Segato <[email protected]>
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]".
Quoted 13 lines
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 <[email protected]>--- Documentation/git-tag.txt | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-)Documentation/git-tag.txt +0
-0
Documentation/git-tag.txt to delete, list or verify tags. · line 29
Quoted 5 lines
Documentation/git-tag.txt +1
-1@@ -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.
Quoted 11 lines
Unless
-m <msg>or-F <file>is given, an editor is started for the user to type in the tag message.Documentation/git-tag.txt +0
-0@@ -36,6 +36,11 @@ are absent, `-a` is implied. Otherwise just a tag reference for the SHA-1 object name of the commitobject is
created (i.e. a lightweight tag).+'Annotated' and 'Lightweight' tags are not the same thing for git and you shouldn't
Documentation/git-tag.txt
Quoted 4 lines
Documentation/git-tag.txt +4
-0+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.
Re: [PATCH] git-tag man: when to use lightweight or annotated tags
Quoted 11 lines · Marc Branchaud
Quoted 4 lines · Daniele Segato
From
34fdcb56e5784699ffa327ebfcd2c5cd99b61d2dMon Sep 17 00:00:00 2001
From: Daniele Segato <[email protected]>
Date: Thu, 25 Jul 2013 15:33:18 +0200
Subject: [PATCH] git-tag man: when to use lightweight or annotated tagsWhen 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.
Quoted 7 lines
Quoted 7 lines
Documentation/git-tag.txt +0
-0@@ -26,7 +26,7 @@ to delete, list or verify tags. Unless `-f` is given, the named tag must not yet exist.
Quoted 6 lines
Documentation/git-tag.txt to delete, list or verify tags.
Quoted 3 lines
Documentation/git-tag.txt +1
-1If 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
Quoted 8 lines
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.
Quoted 34 lines
Quoted 11 lines
Unless
-m <msg>or-F <file>is given, an editor is started for the user to type in the tag message.Documentation/git-tag.txt +0
-0@@ -36,6 +36,11 @@ are absent, `-a` is implied. Otherwise just a tag reference for the SHA-1 object name of the commitobject is
created (i.e. a lightweight tag).+'Annotated' and 'Lightweight' tags are not the same thing for git and you shouldn't
Documentation/git-tag.txt
Quoted 4 lines
Documentation/git-tag.txt +4
-0+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.
Quoted 5 lines
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
Re: [PATCHv3] 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.
--- Documentation/git-tag.txt | 9 +++++++++ 1 file changed, 9 insertions(+)
Documentation/git-tag.txt +9 -0
@@ -42,6 +42,15 @@ 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. +The tag objects (created with `-a`, `s`, or `-u`) are called 'annotated' tags, +they contains a creation date, the tagger name and e-mail, a tagging message +and, eventually, the GNUPG signing and verification data. While a +'lightweight' tag is simply a name for an object (usually a commit object). + +'Annotated' tag are meant for release while 'lightweight' tags are meant +for private or temporary object labels, thus most git commands ignore +lightweight tags by default. + OPTIONS -------
Signature · 1 line
1.7.10.4
Re: [PATCHv3] git-tag man: when to use lightweight or annotated tags
Quoted 4 lines · Daniele Segato
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 <[email protected]>
The intent of your patch seems reasonable to me. There are a few minor language and typographical mistakes, and the patch itself is whitespace-damaged.
I also do not know that it is accurate to say "most git commands ignore lightweight tags". It is really only "naming" ones like "git describe".
Here is a re-send of your patch with the fixups I would recommend.
-- >8 --
From: Daniele Segato <[email protected]>
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.
--- Documentation/git-tag.txt | 11 +++++++++++ 1 file changed, 11 insertions(+)
Documentation/git-tag.txt +11 -0
@@ -42,6 +42,17 @@ is used to specify custom GnuPG binary. 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 -------
Signature · 1 line
1.8.3.rc1.30.gff0fb75
Jonathan Nieder
Reviewed-byRe: [PATCHv3] git-tag man: when to use lightweight or annotated tags
Quoted 6 lines · Jeff King
Documentation/git-tag.txt +0
-0@@ -42,6 +42,17 @@ is used to specify custom GnuPG binary. GnuPG key for signing. The configuration variable `gpg.program` is used to specify custom GnuPG binary.
Documentation/git-tag.txt is used to specify custom GnuPG binary. · line 54
Quoted 10 lines
Documentation/git-tag.txt +10
-0+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.
Very readable, and I think this is a good start.
Eventually the description section should probably be tweaked to start by explaining what the command is actually for. ;-)
Re: [PATCHv3] git-tag man: when to use lightweight or annotated tags
Quoted 2 lines · Jonathan Nieder
Eventually the description section should probably be tweaked to start by explaining what the command is actually for. ;-)
Elaborating from this suggestion you gave me I tried to rewrite/rearrange the description moving things around a little.
Here's what I've come out with, what do you think about it?
DESCRIPTION
-----------
A tag is a non-mutable reference name (in refs/tags/) to an object (usually a commit).
If one of -d/-l/-v options is given the command will delete, list or verify tags.
If one of -a, -s, or -u <key-id> is passed, the command
creates both the reference and a 'tag' object containing a creation date, the tagger name and e-mail, a tag message and an optional GnuPG signature. Unless -m <msg> or -F <file> is given, an editor is started for the user to type in the tag message.
Otherwise just a tag reference for the SHA-1 object name of the commit object is created (i.e. a lightweight tag).
Unless -f is given, the named tag must not yet exist.
If -m <msg> or -F <file> is given and -a, -s, and -u <key-id> are absent, -a is implied.
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 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; 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.
--
Cheers,
Daniele Segato
Re: [PATCHv3] git-tag man: when to use lightweight or annotated tags
Quoted 41 lines · Daniele Segato
Quoted 2 lines · Jonathan Nieder
Eventually the description section should probably be tweaked to start by explaining what the command is actually for. ;-)
Elaborating from this suggestion you gave me I tried to rewrite/rearrange the description moving things around a little.
Here's what I've come out with, what do you think about it?
DESCRIPTION
-----------A tag is a non-mutable reference name (in
refs/tags/) to an object (usually a commit).If one of
-d/-l/-voptions is given the command will delete, list or verify tags.If one of
-a,-s, or-u <key-id>is passed, the command creates both the reference and a 'tag' object containing a creation date, the tagger name and e-mail, a tag message and an optional GnuPG signature. Unless-m <msg>or-F <file>is given, an editor is started for the user to type in the tag message.Otherwise just a tag reference for the SHA-1 object name of the commit object is created (i.e. a lightweight tag).
Unless
-fis given, the named tag must not yet exist.If
-m <msg>or-F <file>is given and-a,-s, and-u <key-id>are absent,-ais implied.A GnuPG signed tag object will be created when
-sor-u <key-id>is used. When-u <key-id>is not used, the committer identity for the current user is used to find the GnuPG key for signing. The configuration variablegpg.programis used to specify custom GnuPG binary.
Quoted 8 lines
Tag objects (created with
-a,s, or-u) are called "annotated" tags; 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.
I suppose there's no interest in this anymore
thanks anyway,
Regards,
Daniele Segato
Marc Branchaud
Reviewed-byRe: [PATCHv3] git-tag man: when to use lightweight or annotated tags
In reply to Jeff KingQuoted 7 lines · Jeff King
Quoted 4 lines · Daniele Segato
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 <[email protected]>
Quoted 8 lines
The intent of your patch seems reasonable to me. There are a few minor language and typographical mistakes, and the patch itself is whitespace-damaged.
I also do not know that it is accurate to say "most git commands ignore lightweight tags". It is really only "naming" ones like "git describe".
Here is a re-send of your patch with the fixups I would recommend.
I'm happy with Peff's version.
(Daniele, don't feel put off because Jonathan & I are accepting Peff's text.
If you think it still needs improving please speak up!)
M.
Quoted 36 lines
-- >8 --
From: Daniele Segato <[email protected]>
Subject: [PATCH] docs/git-tag: explain lightweight versus annotated tagsStress 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 <[email protected]>Signed-off-by Jeff King <[email protected]>--- Documentation/git-tag.txt | 11 +++++++++++ 1 file changed, 11 insertions(+)Documentation/git-tag.txt +11
-0@@ -42,6 +42,17 @@ is used to specify custom GnuPG binary. 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 -------
Re: [PATCHv3] git-tag man: when to use lightweight or annotated tags
Quoted 17 lines · Marc Branchaud
Quoted 7 lines · Jeff King
Quoted 4 lines · Daniele Segato
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 <[email protected]>Quoted 8 lines
The intent of your patch seems reasonable to me. There are a few minor language and typographical mistakes, and the patch itself is whitespace-damaged.
I also do not know that it is accurate to say "most git commands ignore lightweight tags". It is really only "naming" ones like "git describe".
Here is a re-send of your patch with the fixups I would recommend.
Quoted 8 lines
I'm happy with Peff's version.
Reviewed-by Marc Branchaud <[email protected]>(Daniele, don't feel put off because Jonathan & I are accepting Peff's text.
If you think it still needs improving please speak up!)M.
Thank you all. Will apply.
Quoted 37 lines
Quoted 37 lines
-- >8 --
From: Daniele Segato <[email protected]>
Subject: [PATCH] docs/git-tag: explain lightweight versus annotated tagsStress 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 <[email protected]>Signed-off-by Jeff King <[email protected]>--- Documentation/git-tag.txt | 11 +++++++++++ 1 file changed, 11 insertions(+)Documentation/git-tag.txt +11
-0@@ -42,6 +42,17 @@ is used to specify custom GnuPG binary. 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 -------
Re: [PATCHv3] git-tag man: when to use lightweight or annotated tags
Quoted 19 lines · Junio C Hamano
Quoted 17 lines · Marc Branchaud
Quoted 15 lines · Jeff King
Quoted 4 lines · Daniele Segato
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 <[email protected]>The intent of your patch seems reasonable to me. There are a few minor language and typographical mistakes, and the patch itself is whitespace-damaged.
I also do not know that it is accurate to say "most git commands ignore lightweight tags". It is really only "naming" ones like "git describe".
Here is a re-send of your patch with the fixups I would recommend.
Quoted 7 lines
Quoted 7 lines
I'm happy with Peff's version.
Reviewed-by Marc Branchaud <[email protected]>(Daniele, don't feel put off because Jonathan & I are accepting Peff's text.
If you think it still needs improving please speak up!)
I'm not feeling putting off. I thank you for the help you gave me. Hopefully I'll be able to provide a better patch next time.
Quoted 4 lines
Quoted 1 line
M.Thank you all. Will apply.
I'm probably too late, I did proposed another version of the page tweaking all the description part in response to Jonathan Nieder and re-using the Jeff King proposition.
I've been busy in the last days and couldn't reply before now.
I'll understand if you don't like it and don't want to lose more time on this.
Regards,
Daniele Segato
Re: [PATCHv3] git-tag man: when to use lightweight or annotated tags
In reply to Jeff KingQuoted 10 lines · Jeff King
Quoted 4 lines · Daniele Segato
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 <[email protected]>The intent of your patch seems reasonable to me. There are a few minor language and typographical mistakes, and the patch itself is whitespace-damaged.
Hi Jeff,
thanks for the feedback, very appreciated.
But I don't understand what's wrong with the whitespaces.
Can you explain to me what's wrong and how I can avoid the issue?
I use thunderbird in text mode to send emails, should I use something else? what?
Quoted 6 lines
I also do not know that it is accurate to say "most git commands ignore lightweight tags". It is really only "naming" ones like "git describe".
Here is a re-send of your patch with the fixups I would recommend.
Thanks, it's obviously better.
I'll send this new version as soon as you or someone else explain me how to fix the whitespace damage.
Quoted 36 lines
-- >8 --
From: Daniele Segato <[email protected]>
Subject: [PATCH] docs/git-tag: explain lightweight versus annotated tagsStress 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 <[email protected]>Signed-off-by Jeff King <[email protected]>--- Documentation/git-tag.txt | 11 +++++++++++ 1 file changed, 11 insertions(+)Documentation/git-tag.txt +11
-0@@ -42,6 +42,17 @@ is used to specify custom GnuPG binary. 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 -------
Re: [PATCHv3] git-tag man: when to use lightweight or annotated tags
From: "Daniele Segato" <[email protected]>
Quoted 14 lines · Jeff King
Quoted 10 lines · Daniele Segato
Quoted 5 lines
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 <[email protected]>The intent of your patch seems reasonable to me. There are a few minor language and typographical mistakes, and the patch itself is whitespace-damaged.
Hi Jeff,
Quoted 7 lines
thanks for the feedback, very appreciated.
But I don't understand what's wrong with the whitespaces.
Can you explain to me what's wrong and how I can avoid the issue?
I use thunderbird in text mode to send emails, should I use something else? what?
Try 'git format-patch' and 'git send-email'. The format-patch man page even has a note about Thunderbird corruptions.
Philip
Quoted 12 lines
Quoted 7 lines
I also do not know that it is accurate to say "most git commands ignore lightweight tags". It is really only "naming" ones like "git describe".
Here is a re-send of your patch with the fixups I would recommend.
Thanks, it's obviously better.
I'll send this new version as soon as you or someone else explain me how to fix the whitespace damage.
[snip]
Re: [PATCHv3] git-tag man: when to use lightweight or annotated tags
Quoted 5 lines · Philip Oakley
Try 'git format-patch' and 'git send-email'. The format-patch man page even has a note about Thunderbird corruptions.
Philip
Well I use Thunderbird as well for regular communication except for sending patches.
The kernel documentation has also some words about Thunderbird
https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/email-clients.txt
Given so many steps, I also configured git send-email, which makes sure that patches are uncorrupted.
For gmail add these lines to your ~/.gitconfig
[sendemail]
from = Your Name <[email protected]>
smtpserver = /usr/bin/msmtp
smtpuser = emailaddress
smtpencryption = tls
chainreplyto = false
confirm = auto
Then you'd need to have msmtp installed and have the following in the file ~/.msmtprc
# Example for a user configuration file
# Set default values for all following accounts.
defaults
tls ontls_trust_file /usr/share/ncat/ca-bundle.crt
logfile ~/.msmtp.log
# My email service
account gmail
host smtp.gmail.com
port 587
from [email protected]
auth on
user [email protected]
password mysecret
account default : gmail
I think it would also work without having git relying on msmtp by now, but I'd be too lazy to change my existing working setup.
Stefan
Re: [PATCHv3] git-tag man: when to use lightweight or annotated tags
Quoted 18 lines · Stefan Beller
Quoted 5 lines · Philip Oakley
Try 'git format-patch' and 'git send-email'. The format-patch man page even has a note about Thunderbird corruptions.
Philip
Well I use Thunderbird as well for regular communication except for sending patches.
The kernel documentation has also some words about Thunderbird
https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/email-clients.txtGiven so many steps, I also configured git send-email, which makes sure that patches are uncorrupted.
For gmail add these lines to your ~/.gitconfig[sendemail]
[snip]
Quoted 3 lines
Then you'd need to have msmtp installed and have the following in the file ~/.msmtprc
[snip]
Quoted 4 lines
I think it would also work without having git relying on msmtp by now, but I'd be too lazy to change my existing working setup.
Hi Paolo, Philip, Stefan,
thank you, you've been very kind.
I think I've set it up, I'll try with the next patch, if any!
Regards,
Daniele Segato
Re: [PATCH] git-tag man: when to use lightweight or annotated tags
In reply to Daniele SegatoQuoted 4 lines · Daniele Segato
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.
Re: [PATCH] git-tag man: when to use lightweight or annotated tags
Quoted 21 lines · Marc Branchaud
Quoted 4 lines · Daniele Segato
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.
Quoted 2 lines
M.
Thanks.
That helps a bit in understanding how I fit into the ml!
Cheers,
Daniele Segato
Quoted 6 lines · Junio C Hamano
Quoted 3 lines · Daniele Segato
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.
Quoted 6 lines
Nicely explained.
This is one of those "we who worked on Git (not worked "with" Git) for a long time _know_ it and do not need it to be explained, and we didn't spot that it is not explained in the documentation for new people."
Good!
Any change in adding an option to filter tags list by annotated only?
Quoted 3 lines
Care to roll a documentation patch (and get a commit count for yourself ;-)?
I tried, just sent the patch, hopefully I managed to follow the guide I found here: http://repo.or.cz/w/git.git?a=blob;f=Documentation/SubmittingPatches;hb=HEAD
As you suggested I removed the "title" line and the reference to git describe default.
If I did something wrong please explain me what and I'll fix it
Quoted 2 lines
Thanks.
You're Welcome :-)
Cheers,
Daniele Segato