Himanshu SharmaSoftware engineer
Let’s talk

Git and GitHub · Lesson 23 of 30

Marking releases with Git tags

Create lightweight and annotated tags, list and inspect them, push them to a remote, delete them, and use semantic version names to mark releases.

12 minPower toolsUpdated 14 November 2026

Awaiting technical review. This lesson is readable but not yet listed in search engines.

By the end of this lessonTag a commit as a release, list and inspect tags, share them with a remote, and use git describe to name any commit relative to the latest tag.

What you can do after this lesson

You will mark important commits, usually releases, with names that never move. Where a branch label slides forward every time you commit, a tag stays put. That makes tags the right tool for "this is version 1.0".

Lightweight and annotated tags

The simplest tag is a name attached to the current commit:

bash
git tag v0.1.0
git tag
text
v0.1.0

That is a lightweight tag: nothing but a pointer. An annotated tag is a proper stored object with a message, the tagger's identity and a date. Use it for releases:

bash
git tag -a v1.0.0 -m "First public release"
git tag -l "v*"
text
v0.1.0
v1.0.0

-l with a pattern filters the list. Inspect an annotated tag with git show:

bash
git show v1.0.0 --stat
text
tag v1.0.0
Tagger: Asha Rao <asha@example.com>
Date:   Tue Nov 10 10:00:00 2026 +0000

First public release

commit 861ab87577f9fd28c39208cae9056d95ebf007a8
Author: Asha Rao <asha@example.com>
Date:   Tue Nov 10 10:00:00 2026 +0000

    Add page

This output was captured on 2026-11; hashes and dates differ for you. Notice the tagger section: that is the extra information a lightweight tag lacks.

Tagging an older commit

Forgot to tag a release? Tag it later by giving a commit:

bash
git tag -a v0.9.0 HEAD~1 -m "Late tag"
git log --oneline --decorate
text
74f03b8 (HEAD -> main) Another change
861ab87 (tag: v1.0.0, tag: v0.9.0, tag: v0.1.0) Add page

The log shows tags next to commits as tag: name. Several tags may share one commit.

Naming releases: semantic versions

A common convention called semantic versioning writes versions as MAJOR.MINOR.PATCH, for example v2.4.1. By convention, you raise the patch number for bug fixes, the minor number for backward-compatible new features and the major number for changes that may break users. Many projects follow it and prefix the tag with v. It is a convention, not something Git checks, and teams may choose other schemes, such as dates.

Sharing tags

A plain git push does not send tags. Push one by name, or push all annotated tags pointing at commits you are pushing:

bash
git push origin v1.0.0
git push --follow-tags origin main
text
To /home/you/fp/work/readinglist.git
 * [new tag]         v1.0.0 -> v1.0.0

You can confirm what the remote holds with git ls-remote --tags origin. For an annotated tag it lists two entries: the tag object, and the commit it points to marked with ^{}:

text
8f7248441e57c64967904a99a113a8e2c830ad6d	refs/tags/v1.0.0
f1ffaf819bae57e216f45e8bd6d2aa4fd2668bfb	refs/tags/v1.0.0^{}

git push origin --delete v1.0.0 removes a tag from the remote. Hosting services such as GitHub use pushed tags to offer releases: a web page for a version with notes and downloadable files. Creating that page happens in the browser and is described in the hosting service's documentation.

Looking at a tagged version

To view the code as it was at a tag, check it out in detached mode:

bash
git switch --detach v1.0.0
git switch main
text
HEAD is now at 861ab87 Add page
Previous HEAD position was 861ab87 Add page
Switched to branch 'main'

Do not commit in detached HEAD unless you intend to create a branch: git switch -c hotfix/1.0.1 v1.0.0 starts a branch from the tag, which is how you fix an old release.

Naming any commit with git describe

git describe builds a readable name from the nearest earlier tag:

bash
git describe --tags
text
v1.0.0-1-g74f03b8

That reads: the latest tag is v1.0.0, we are one commit past it, and the current commit starts 74f03b8. Build scripts often embed this string as a version number. On a commit exactly at a tag it prints the tag name alone. Note that plain git describe considers only annotated tags unless you add --tags.

Deleting and correcting tags

git tag -d v0.1.0 deletes a local tag (Deleted tag 'v0.1.0' (was 861ab87)). To list newest first, use git tag --sort=-creatordate. Treat published tags as permanent. If you tagged the wrong commit and nobody has used the tag yet, delete it locally and on the remote and recreate it. If anyone might have used it, leave it and make a new version instead, because two people holding different commits under one tag name is a source of long confusion.

Tags and branches together

A useful mental picture is that a branch is a bookmark you move while working, and a tag is a stamp you press once. Teams often combine them: work happens on branches, the finished state is merged to main, and then a tag stamps exactly that commit as a release. Later, if someone reports a bug in version 1.0.0, you can check out the tag, reproduce the problem on the precise code that shipped, and start a fix branch from there.

Common mistakes

  • Forgetting to push tags. Teammates and the hosting service never see them.
  • Using lightweight tags for releases. You lose the tagger, date and message.
  • Moving a published tag. Builds and deployments may rely on it.
  • Inconsistent naming. Pick v1.2.3 or 1.2.3, not both.
  • Tagging before the final commit. Tag the exact commit that was tested and released.

Exercise

  1. In a practice repository, tag the current commit v0.1.0 as a lightweight tag and v1.0.0 as an annotated tag with a message.
  2. Make another commit and run git describe --tags.
  3. Push main and the tag to a local bare remote with --follow-tags, and verify with git ls-remote --tags origin.
Show one possible answer
bash
git tag v0.1.0
git tag -a v1.0.0 -m "First release"
git commit --allow-empty -m "Another change"
git describe --tags
git push --follow-tags origin main
git ls-remote --tags origin

git describe --tags prints something like v1.0.0-1-gabc1234. Only the annotated tag is sent by --follow-tags; to send the lightweight one use git push origin v0.1.0.

Next: Copying single commits with cherry-pick.

Key points

  • A tag is a permanent human-friendly name for one commit, usually used for release versions.
  • A lightweight tag is just a name; an annotated tag (git tag -a) also stores a message, tagger and date and is preferred for releases.
  • Tags are not pushed by default: use git push origin <tag> or git push --follow-tags.
  • git describe --tags names the current commit relative to the nearest tag, such as v1.0.0-1-g74f03b8.
  • Do not move or reuse a tag that has been published; create a new one instead.

Check yourself

1. How does an annotated tag differ from a lightweight tag?
2. You created tag v1.0.0 locally. Teammates cannot see it. Why?
3. What does git describe --tags print as v1.0.0-1-g74f03b8?
4. Why avoid moving a tag that has already been pushed?