Why should I care about lightweight vs. annotated tags?

Question

I switched from Subversion to Git as my day-to-day VCS last year and am still trying to grasp the finer points of "Git-think".

The one which has been bothering me lately is "lightweight" vs. annotated vs. signed tags. It seems pretty universally accepted that annotated tags are superior to lightweight tags for all real uses, but the explanations I've found for why that's the case always seem to boil down to either "because best practices" or "because they're different". Unfortunately, those are very unsatisfying arguments without knowing why it's best practices or how those differences are relevant to my Git usage.

When I first switched to Git, lightweight tags seemed to be the best thing since sliced bread; I could just point at a commit and say "that was 1.0". I'm having trouble grasping how a tag could ever need to be more than that, but I certainly can't believe that the Git experts of the world prefer annotated tags arbitrarily! So what's all the hubbub about?

(Bonus points: Why would I ever need to sign a tag?)

EDIT

I've been successfully convinced that annotated tags are a Good Thing — knowing who tagged and when is important! As a follow-up, any advice on good tag annotations? Both git tag -am "tagging 1.0" 1.0 and trying to summarize the commit log since the previous tag feel like losing strategies.

Answer 1

The big plus of an annotated tag is that you know who created it. Just like with commits, sometimes it's nice to know who did it. If you're a developer and you see that v1.7.4 has been tagged (declared ready) and you're not so sure, who do you talk to? The person whose name is in the annotated tag! (If you live in a distrustful world, this also keeps people from getting away with tagging things they shouldn't.) If you're a consumer, that name is a stamp of authority: that's Junio Hamano saying this version of git is hereby released.

The other metadata can be helpful too - sometimes it's nice to know when that version was released, not just when the final commit was made. And sometimes the message can even be useful. Maybe it helps explain the purpose of that particular tag. Maybe the tag for a release candidate contains a bit of a status/to-do list.

Signing tags is pretty much like signing anything else - it provides one more level of security for the paranoid. Most of us aren't ever going to use it, but if you really want to verify everything before you put that software on your computer, you might want it.

Edit:

As for what to write in a tag annotation, you're right - there's not always much useful to say. For a version number tag, it's implicitly understood that it marks that version, and if you're happy with your changelogs elsewhere, there's no need to put one there. In this case, it's really the tagger and date that are the most important. The only other thing I can think of is some sort of stamp of approval from a test suite. Have a look at git.git's tags: they all just say something like "Git 1.7.3 rc1"; all we really care about is Junio Hamano's name on them.

However, for less obviously named tags, the message could become much more important. I could envision tagging a specific special-purpose version for a single user/client, some important non-version milestone, or (as mentioned above) a release candidate with extra information. The message is then much more useful.

Answer 2

My personal, slightly different view on that topic:

• Annotated tags are those tags meant to be published for other developers, most probably new versions (which should also be signed). Not only to see who tagged and when it was tagged, but also why (usually a changelog).
• Lightweight are more appropriate for private use, that means tagging special commits to be able to find them again. May it be to review them, check them out to test something or whatever.