Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 78 ยท Branching and Merging

Tags and Releases

Learn Git tags: lightweight vs annotated, tagging old commits, listing and sorting versions, pushing tags, semantic versioning, release notes with git log and git describe.

A branch name moves every time you commit. Sometimes you want the opposite: a name that stays on one commit forever, such as "this is exactly what we shipped as version 1.4.0". That is what a tag is. Tags mark important points in history, almost always releases, and they let you return to them years later with a single word.

In this lesson you will learn the two kinds of tags (lightweight and annotated) and why professionals prefer one of them, how to tag the current or an older commit, how to list, sort and delete tags, how to share them with a remote, how version numbers work (semantic versioning), and how to produce release notes from the commit history. The final section shows git describe, which names any commit relative to the nearest tag.

Tag or branch?

Both are names for commits, stored as small files, but they behave differently:

Branch Tag
Moves when you commit Yes (the one you are on) No, it stays on its commit
Meant for Ongoing work A fixed point such as a release
Can carry its own message and author No Yes, if annotated
Can be signed No Yes

You can check out a tag, but you will be on a detached HEAD, because there is no branch to advance. To continue work from a release, create a branch at the tag: git switch -c hotfix-1.4 v1.4.0.

Lightweight and annotated tags

There are two kinds, and they differ in what Git stores.

  • A lightweight tag is only a name pointing at a commit, exactly like a branch that never moves. It stores no extra information.
  • An annotated tag is a full object in Git's database (how objects work). It records the tagger's name and email, a date, and a message, and it points at the commit. It can also be signed with GPG or SSH.

Create the lightweight kind with git tag name, and the annotated kind with git tag -a name -m "message". Passing -m alone (without -a) also makes an annotated tag.

Bash Create both kinds of tag and compare them

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

git cat-file -t reports the object type: light resolves straight to a commit, while v1.0.0 is a tag object that sits between the name and the commit. git tag -n prints each tag's first message line; the lightweight one shows the commit's subject instead because it has no message of its own. git show on an annotated tag prints the tag header (who tagged, when, and the message) and then the commit.

Which should you use? Use annotated tags for anything others will see: releases, deployments, milestones. They record who and when, work with git describe by default, and can be signed. Use lightweight tags for private, temporary bookmarks ("before-refactor") that you will delete soon.

Tagging an older commit

You do not have to tag the commit you are on. Pass a commit after the tag name, and forgotten releases can be tagged after the fact. (An annotated tag made later records the tagging time, not the commit's time; set GIT_COMMITTER_DATE to backdate it if you must.)

Bash Tag an old commit, list and sort versions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The default listing is alphabetical, so v1.10.0 appears before v1.2.0, which is wrong for versions. --sort=v:refname compares the numbers inside the names, and git config --global tag.sort v:refname makes that the default. git tag -l 'pattern' filters by shell-style wildcard, and --points-at lists tags on a given commit. To see a whole tag listing with dates, use git for-each-ref refs/tags --format='%(refname:short) %(creatordate:short)'.

Moving and deleting tags

Delete a local tag with git tag -d v1.0.0. To change where a tag points, you must force it with git tag -f, but think twice: a tag is meant to be a stable promise. If anyone has already fetched it, they keep the old meaning, and Git will not update their copy silently. If a release is wrong, publish a new version (v1.0.1) instead of moving the old tag.

Semantic versioning

Most projects name release tags with semantic versioning (SemVer): MAJOR.MINOR.PATCH, for example 2.4.1.

  • Increase PATCH for backward-compatible bug fixes: 2.4.0 becomes 2.4.1.
  • Increase MINOR for new backward-compatible features: 2.4.1 becomes 2.5.0 (and PATCH resets to 0).
  • Increase MAJOR for incompatible changes: 2.5.0 becomes 3.0.0.
  • Pre-releases add a suffix: 3.0.0-rc.1, 3.0.0-beta.2. Build metadata follows a plus sign: 3.0.0+20260101.

Prefix the tag with v (v2.4.1) or not; just be consistent, because tools match on the pattern. SemVer is a promise to your users about what an upgrade may break, which makes the tag name meaningful. More about versioning and changelogs appears in Contributing to Open Source, and the release automation project builds a bump script.

Sharing tags

Tags are local until you share them, and git push does not push them by default. You must send them explicitly.

Bash Push tags to a local remote and delete one there

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

git ls-remote --tags origin lists what the server holds; it was empty (zero lines) after a plain push of main. Then three ways to publish tags, all shown above:

  • git push origin <tag> sends one tag.
  • git push --follow-tags sends your commits plus the annotated tags that point at them: a good default for release flows (git config push.followTags true makes it permanent).
  • git push origin --tags sends every tag, including lightweight ones and old experiments. Use it carefully.

The final listing shows each annotated tag twice: refs/tags/v1.0.0 is the tag object and the entry ending in ^{} is the commit it points at (Git calls that "peeling"). The lightweight scratch tag is gone because we deleted it on the server. To delete a remote tag use git push origin --delete tagname, or the older git push origin :refs/tags/tagname. Deleting it elsewhere does not remove copies that others already fetched. git fetch --tags brings in tags from the remote (git fetch already follows tags that point at commits it downloads).

Release notes from the history

A tag is also a boundary for a revision range. v1.0.0..v1.1.0 means "commits reachable from v1.1.0 but not from v1.0.0", exactly what happened in that release. That gives you release notes for free if your commit subjects are good (see Making Good Commits).

Bash Generate release notes between two tags

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The .. range is explained fully in Revision Syntax. %s is the commit subject and %h the short hash; --grep filters by message, so a convention such as feat: and fix: (see Conventional Commits) lets you group notes automatically. git shortlog -sn summarizes commits per author.

git describe: naming a commit from the nearest tag

git describe answers "what version is this commit?". If the commit has an annotated tag it prints the tag. Otherwise it prints the nearest earlier tag, the number of commits since, and the abbreviated hash, prefixed with g for Git:

TEXT
v1.1.0-1-g5c0a9d3
โ”‚      โ”‚  โ””โ”€โ”€ "g" + abbreviated hash of the commit
โ”‚      โ””โ”€โ”€โ”€โ”€โ”€ 1 commit after the tag
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ nearest annotated tag
Bash Use git describe to name commits

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

By default git describe only considers annotated tags, so our lightweight tag quick was ignored until we passed --tags. Build systems love this: git describe --tags --always --dirty produces a version string such as v1.0.0-2-g1f3a9c0-dirty to stamp into binaries so that every build identifies the exact source it came from. --always falls back to a bare hash when no tag exists at all, and --dirty appends -dirty when the working tree has uncommitted changes.

Pitfalls professionals know

  • Forgetting to push tags is the classic mistake: your teammates and your CI never see the release. Check git ls-remote --tags origin.
  • Moving a published tag breaks reproducibility. Create a new patch version instead.
  • Tag names can clash with branch names. If v1 is both, Git warns that the reference is ambiguous. Keep a clear scheme such as v* for tags.
  • Annotated vs lightweight in describe, --follow-tags and signing is where the difference bites; default to annotated for releases.
  • Release platforms add to tags. GitHub "Releases" attach notes and files to a tag; they do not replace it. See GitHub Basics.
  • Tag from a clean, tested commit, usually on main or a release branch, after CI passes.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the main difference between a lightweight and an annotated tag?

    Annotated tags are real Git objects with metadata and can be signed. A lightweight tag is just a ref pointing to a commit.
  2. 2. You ran git push on main. Why does your teammate not see the tag v2.0.0 you created?

    Push tags with git push origin v2.0.0, git push --tags or git push --follow-tags.
  3. 3. Which range lists the commits that are in release v1.1.0 but not in v1.0.0?

    A..B means commits reachable from B but not from A. Use git log v1.0.0..v1.1.0 for release notes.
  4. 4. git describe prints v1.2.0-5-g3a4b5c6. What does it mean?

    The format is nearest-tag, number of commits since it, then g plus the abbreviated commit hash.
  5. 5. A project fixes a bug that does not change its public interface. Under semantic versioning, which number goes up in 2.4.1?

    Backward-compatible bug fixes increase PATCH. New compatible features increase MINOR, incompatible changes increase MAJOR.

Summary

  • A tag is a fixed name for a commit; unlike a branch it does not move.
  • Use annotated tags (git tag -a v1.0.0 -m "...") for releases; lightweight tags (git tag name) are just bookmarks.
  • Tag an older commit by naming it: git tag -a v1.0.0 <commit>. List with git tag -l, sort versions with --sort=v:refname.
  • Tags are not pushed by default: use git push origin <tag>, --follow-tags or --tags; delete remotely with git push origin --delete <tag>.
  • Semantic versioning (MAJOR.MINOR.PATCH) tells users what an upgrade may break.
  • git log v1.0.0..v1.1.0 produces release notes; git describe --tags --always --dirty names any commit for build stamps.

Next: Stashing Work in Progress