In what circumstances should I add the `-a` flag to the git tag command?

Question

I am aware of the technical differences between the two types of commands (usage without the -a flag creates a lightweight tag which is essentially a branch that never moves, while usage with -a creates a full object in Git's object database which includes the committer's name, email, etc.).

The question is: which one should I use in my projects (to indicate release versions on Github, for example)? And if one is hugely preferred over another, why does the other option exist? What are the use cases for each version?

Answer 1

I'd say that with published work, you should just always use annotated tags. That extra information is never going to harm you.

Lightweight tags strike me as being more for when you're being lazy. Maybe a temporary tag (just make sure you don't accidentally push it; really you could just use a branch), or maybe a personal repo where there's not much use for the extra information. My guess is that a lot of smaller projects do this too; they're just not really concerned with the information. Probably there's only one integrator, no one's concerned with verifying signed tags, and they're just simple markers of release versions. (I still think you should prefer annotated tags, just in case!)

Another way of thinking of it: lightweight tags are kind of like writing a really bad commit message. You really shouldn't do it, but sometimes people do, usually when no one's watching.

Answer 2

What are the use cases for each version?

man git-tag says:

Annotated tags are meant for release while lightweight tags are meant for private or temporary object labels.

And certain behaviors do differentiate between them in ways that this recommendation is useful e.g.:

• annotated tags can contain a message, creator, and date different than the commit they point to. So you could use them to describe a release without making a release commit. Lightweight tags don't have that extra information.
• git push --follow-tags will only push annotated tags
• git describe without command line options only sees annotated tags

See also:

• Why should I care about lightweight vs. annotated tags?
• What is the difference between an annotated and unannotated tag?

Answer 3

If you want to to push/fetch them, then you should use annotated tags.

Answer 4

I had an opinion on this a few years back that I think may still be relevant.

Answer 5

The most common style is to use annotated tags for permanent tags, things which you expect to push and you expect other people to look at. Lightweight tags are then used for temporary tags, things which you will not push and which you do not want other people to see.

Answer 6

There are a couple of considerations:

1. What capabilities do you need?
2. Do you need git(1) to respect it as a “first-class” tag?

Capabilities

An annotated tag lets you create a message and sign it. It also gives you metadata about the tagger. Do you need that?

Sometimes I just want to mark a commit temporarily, like “before big regression” or “before big rewrite”. I don’t need any tag message for that, and in fact being prompted about it would be distracting.

But for a release tag you might want to write a tag message. And maybe also sign it.

First-class tag

With a lightweight tag you’re always going to have to check whether whatever Git manpage really meant “tag” as in “any tag” or specifically “annotated tag”, i.e. what I’m calling a “first-class” tag.

At my job we didn’t really care one way or the other about whether our release tags were lightweight or annotated. Right up until we noticed that git-describe(1) didn’t behave like we expected, since we had a mix of lightweight and annotated tags (this command only looks at annotated tags by default).

So we started using annotated tags. Not because of the first consideration (capabilities) since:

1. The tag message for v5.6.7 might just be… v5.6.7
2. It doesn’t matter who made the tag (the author)
3. We don’t sign our tags (or anything)

But using annotated tags turned out to be more convenient just because then we are using a “release tag”, as far as the git(1) suite is concerned.