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 command (usage without -a creates a lightweight tag which is essentially a branch that never moves, 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.