What is the difference between lightweight and annotated Git tags?
Quick answer
A lightweight tag is a name pointing directly to a Git object, usually a commit. An annotated tag adds a separate tag object containing a tagger, date, and message; it can also include a cryptographic signature. Both are tags, not branch names. Use a lightweight tag for a simple local marker and an annotated tag when you want the tag itself to carry release information. [S1]
The question, the details, the next step.
What is the basic difference between a lightweight tag and an annotated tag?
A lightweight tag is a reference name pointing directly to an object, usually a commit. An annotated tag creates a separate tag object that records information about the tag, including the tagger’s name and email, creation date, and a message; it can also have a cryptographic signature. [S1]
In short: lightweight means a simple pointer; annotated means a pointer backed by a record describing the tagging event. Neither is a branch. Git keeps tags under refs/tags/, while a branch is a separate kind of reference. [S1]
What commands create each kind, and when might I use them?
For a local lightweight tag, use git tag v1.0. For an annotated tag with a message, use git tag -a v1.0 -m "Release 1.0". Git documents these forms; configuration may affect signing behavior. [S1]
For example, if you are marking a commit for your own local reference, a lightweight tag may be enough. If you want to mark a release and have the tag carry a message such as Release 1.0, an annotated tag provides that record. These are practical examples, not rules: choose based on whether you need tag metadata.
How can I compare the two without confusing tags with branches?
Compare them by what the tag records, not by treating one as a kind of branch:
- Lightweight: a reference name pointing directly to an object, usually a commit. [S1]
- Annotated: a separate tag object with tagger details, a date, and a message; a signature is optional. [S1]
- Branch distinction: a tag name and a branch name refer to different kinds of Git references. [S1]
If you need to record why a commit was marked, an annotated tag gives you a place for that message. The metadata difference does not mean either type is always better or that a particular workflow requires one.
Can you show a small local example and give me a choice checklist?
Suppose your local project has a commit you want to mark v1.0. For a simple marker, run:
git tag v1.0
For a marker with a message, run:
git tag -a v1.0 -m "Release 1.0"
The first creates a lightweight tag by default; the second creates an annotated tag, absent configuration that changes signing behavior. [S1] These examples create local tags; they do not imply a remote release or publication.
Before choosing, ask:
- Do I only need a name pointing to this object?
- Do I want the tag itself to record a tagger, date, and message?
- Would an optional signature matter for this tag?
- Am I naming a tag rather than intending to create or move a branch?
Choose the lightweight form for a simple marker, or the annotated form when its additional record is useful.
A practical checklist
Decide whether a simple object reference is enough.
Use
git tag NAMEfor a lightweight tag by default.Use
git tag -a NAME -m "MESSAGE"when you want an annotated tag message.Consider whether tagger details, date, or an optional signature matter.
Check that you mean to create a tag, not a branch.
A few more useful answers
Does a lightweight tag have a tag message?
A lightweight tag points directly to an object; the separate message-bearing tag object is characteristic of an annotated tag. [S1]
Is an annotated tag a branch?
No. Git treats tags and branches as separate kinds of references. [S1]
Does the annotated-tag command always create an unsigned tag?
Not necessarily: signing configuration can affect behavior. The documented command example creates an annotated tag absent configuration that changes signing behavior. [S1]
Sources
References used for this guide.
- [S1] Git Reference: git-tag git-scm.com · Checked