git tag

Lightweight or annotated. Releases live here.

🎯 What & why

Mark a specific commit with a name. Two flavors: lightweight (just a ref pointing at a commit, like a branch that doesn't move) and annotated (a real tag object with author, message, optional GPG signature — what you want for releases).

🧠 Mental model

A lightweight tag is refs/tags/<name> containing a commit SHA. An annotated tag is refs/tags/<name> containing a tag object SHA, where the tag object then references the commit. Annotated tags are searchable by git describe, signable, and have their own metadata.

🛠️ Synopsis

git tag [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] [-e]
        <tagname> [<commit> | <object>]
git tag -d <tagname>...
git tag [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]
         [--points-at <object>] [--column[=<options>] | --no-column]
         [--create-reflog] [--sort=<key>] [--format=<format>]
         [--merged <commit>] [--no-merged <commit>] [<pattern>...]
git tag -v [--format=<format>] <tagname>...

🎚️ Switches & options

Flag	What it does
`-a, --annotate`	Make an annotated tag.
`-m "<msg>"`	Tag message (implies `-a`).
`-s, --sign`	GPG-sign the tag.
`-d, --delete`	Delete a tag.
`-l <pattern>`	List tags matching `<pattern>`.
`--points-at <commit>`	List tags pointing at `<commit>`.
`-f, --force`	Replace an existing tag of the same name.

💡 Use cases

Marking releases.
Pinning a specific commit as 'this is the demo version'.
Naming a known-good base for bisects.

🧪 Examples

Lightweight tag at HEAD.

$ git tag v1.2

Annotated tag — what you want for a release.

$ git tag -a v1.2 -m 'release 1.2 — purple theme'

Signed tag.

$ git tag -s v1.2 -m 'release 1.2'

Push tags (they don't go with git push by default).

$ git push origin v1.2
$ git push --tags  # all of them

🎓 Recommendations

Use annotated tags (-a) for anything you'd ever cut a release from. Lightweight tags are fine for personal scratchpads.
Adopt SemVer (vMAJOR.MINOR.PATCH) and stick to it — git describe becomes a useful version oracle.
Tags don't move. If you need to retag, you're doing something wrong.

🪤 Common pitfalls

Tags don't push automatically. Many a 'why isn't my release on origin?' minute has been spent learning this.
Force-pushing a moved tag is a mortal sin in shared repos. Don't.
Annotated tag SHAs are different from the commit SHAs they point at — git rev-parse v1.2 may surprise you.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.