Skip to content
Laviyx Learn

Try

Git and GitHub course menu

Git Tags: Mark Releases with git tag

Mark versions with lightweight and annotated Git tags, list and inspect them, tag old commits, push tags to GitHub, use semantic versioning, and create GitHub Releases.

Beginner6 min readUpdated
On this page

A tag is a permanent name for one commit. Where a branch moves forward with each commit, a tag stays put. Tags are mainly used to mark releases, such as v1.0.0.

Create a tag#

An annotated tag stores a message, the tagger and the date. Use this kind for releases:

Terminal
git tag -a v1.0.0 -m "First public release"
git tag
Output
v1.0.0

A lightweight tag is only a name for a commit, with no extra data:

Terminal
git tag trial-build
git tag -l
Output
trial-build
v1.0.0

Tag an older commit#

Give a commit ID or a reference:

Terminal
git tag -a v0.9.0 HEAD~1 -m "Beta release"
git log --oneline --decorate
Output
0225af6 (HEAD -> main, tag: v1.0.0, tag: trial-build) Add search
94c4f4f (tag: v0.9.0) Add login
fbbd872 First version

Inspect a tag#

Terminal
git show v1.0.0 --no-patch
Output
tag v1.0.0
Tagger: Asha Rao <[email protected]>
Date:   Thu Nov 5 09:15:00 2026 +0530

First public release

commit 0225af684eac8829b80fd45b5df95e1651ead8a4
Author: Asha Rao <[email protected]>
Date:   Thu Nov 5 09:10:00 2026 +0530

    Add search

Filter and delete#

Terminal
git tag -l "v1.*"
git tag -d trial-build
git tag
Output
v1.0.0
Deleted tag 'trial-build' (was 0225af6)
v0.9.0
v1.0.0

Push tags to GitHub#

git push does not send tags by default. Push them separately:

Terminal
git push origin v1.0.0     # one tag
git push origin --tags     # all tags

Delete a tag from GitHub with:

Terminal
git push origin --delete v1.0.0

Go back to a tagged version#

You can look at the code as it was at a tag. This puts you in a state called detached HEAD: you are on a commit rather than a branch.

Terminal
git switch --detach v0.9.0
cat app.txt
Output
HEAD is now at 94c4f4f Add login
v1
login

New commits made here do not belong to any branch. To work from this point, create a branch with git switch -c hotfix. To go back, switch to a branch:

Terminal
git switch -q main
git branch --show-current
Output
main

Semantic versioning#

Most projects number releases as MAJOR.MINOR.PATCH:

PartIncrease it whenExample
MAJORYou make a breaking change1.4.2 to 2.0.0
MINORYou add a feature that stays compatible1.4.2 to 1.5.0
PATCHYou fix a bug1.4.2 to 1.4.3

GitHub Releases#

A Release on GitHub is a page built around a tag, with notes and optional downloadable files. On your repository's page, open Releases, then Draft a new release, choose a tag, and write what changed. GitHub can generate the notes from your merged pull requests.

Common mistakes#

Practice#

Practice exercise

Create an annotated tag v1.1.0 on the latest commit with the message Search release. Print every tag beginning with v1, then print which tag is nearest to the current commit using git describe.

Show solution
Terminal
git tag -a v1.1.0 -m "Search release"
git tag -l "v1*"
git describe
Output
v1.0.0
v1.1.0
v1.1.0

Key takeaway#

Next: Pushing a Project to GitHub.

Finished this lesson?

Related lessons

Git and GitHubGit Branches Explained: git branch and git switchLearn what a Git branch is, create and switch branches with git branch and git switch, list and rename them, delete finished branches, and name branches well.Beginner7 min readGit and GitHubHow to Push a Project to GitHub for the First TimeCreate a GitHub account and repository, connect a local project with git remote add, push it with git push -u origin main, and understand remotes, origin and upstream branches.Beginner6 min readGit and GitHubGit Workflows Compared: GitHub Flow, Git Flow and Trunk-BasedCompare GitHub Flow, trunk-based development and Git Flow: how each one works, when to use it, how teams handle hotfixes and releases, and which to choose.Intermediate3 min read