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:
git tag v0.1.0
git tagv0.1.0That 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:
git tag -a v1.0.0 -m "First public release"
git tag -l "v*"v0.1.0
v1.0.0-l with a pattern filters the list. Inspect an annotated tag with git show:
git show v1.0.0 --stattag 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 pageThis 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:
git tag -a v0.9.0 HEAD~1 -m "Late tag"
git log --oneline --decorate74f03b8 (HEAD -> main) Another change
861ab87 (tag: v1.0.0, tag: v0.9.0, tag: v0.1.0) Add pageThe 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:
git push origin v1.0.0
git push --follow-tags origin mainTo /home/you/fp/work/readinglist.git
* [new tag] v1.0.0 -> v1.0.0You 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 ^{}:
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:
git switch --detach v1.0.0
git switch mainHEAD 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:
git describe --tagsv1.0.0-1-g74f03b8That 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.3or1.2.3, not both. - Tagging before the final commit. Tag the exact commit that was tested and released.
Exercise
- In a practice repository, tag the current commit
v0.1.0as a lightweight tag andv1.0.0as an annotated tag with a message. - Make another commit and run
git describe --tags. - Push
mainand the tag to a local bare remote with--follow-tags, and verify withgit ls-remote --tags origin.
Show one possible answer
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 origingit 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.
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.