Git Tag - How To Use Git Tag | W3Docs Online Git Tutorial

What a Git tag is

A tag is a named reference that points to a specific commit in your Git history. Unlike a branch, which moves forward every time you commit, a tag stays fixed on the commit it was created for. That makes tags ideal for marking meaningful, permanent points in a project — most commonly release versions such as v1.0.0 or v2.3.1.

This page covers how to create the two kinds of tags (annotated and lightweight), how to list and filter them, how to tag past commits, and how to push, inspect, and delete tags.

Creating a Git tag

To create a Git tag, run the command below:

git tag

git tag <name-of-tag>

When creating a tag, replace <name-of-tag> with a semantic identifier for the repository state — for example v1.3. Git supports two kinds of tags: annotated and lightweight. The main difference between them is how much metadata they store.

Annotated vs. lightweight tags

Choosing the right kind of tag matters more than it seems:

Annotated tags are stored as full objects in the Git database. They record the tagger's name, email, and date, carry a tagging message, and can be cryptographically signed and verified with GPG (GNU Privacy Guard). Use them for releases and anything you share with others.
Lightweight tags are just a name pointing at a commit — no extra metadata, no message, no signature. They behave like a private bookmark. Use them for temporary or local markers.

For published versions, prefer annotated tags so the history records who tagged the release and when.

Annotated tags

Git stores annotated tags as full objects in its database. They contain additional metadata, such as the tagger's name, email, and date. Like commits, annotated tags include a tagging message.

Running the command below creates a new annotated tag with the ID v1.3. The configured default text editor will then open, prompting you to enter a tagging message.

git annotated tag

git tag -a v1.3

To supply the message inline and skip the editor, use the -m option:

git annotated tag with inline message

git tag -a v1.3 -m "Release version 1.3"

Lightweight tags

The command below creates a lightweight tag identified as v1.3-lw. Lightweight tags are created without the -a, -s, or -m options. They simply store a pointer to a specific commit object in the .git/refs/tags/ directory.

git lightweight tag

git tag v1.3-lw

Tags list

Run the command below to list stored tags:

git tag command

git tag

As a result, you will see output similar to this:

git tag output

v0.10.0
v0.10.0-rc1
v0.11.0
v0.11.0-rc1
v0.11.1
v0.11.2
v0.12.0
v0.12.0-rc1
v0.12.1
v0.12.2
v0.13.0
v0.13.0-rc1
v0.13.0-rc2

You can use the -l option with a wildcard expression to filter the list of tags:

git tag with wildcard

git tag -l *-rc*
v0.10.0-rc1
v0.11.0-rc1
v0.12.0-rc1
v0.13.0-rc1
v0.13.0-rc2
v0.14.0-rc1
v0.9.0-rc1
v15.0.0-rc.1
v15.0.0-rc.2
v15.4.0-rc.3

Tagging old commits

By default, git tag creates a tag on the commit referenced by HEAD. You can also pass a specific commit reference to tag an older commit instead. Run the git log command to view older commits. In the example below, a merge commit is used for the new tag. To reference a specific commit, provide its SHA hash:

git log

git log --pretty=oneline
29389857951b64cf874c3557a0f3547bd83b899a Merging branch 'crossword'
b4a5697498bd301d84096da251c98a07c7723e65 init method for crossword
89f3aaab4479697da7686c15f77a3d64d9165190 little changes in logic
3a4a271eda8725415634dd79daabbc4d9b6008e Merging branch 'how-it-works'

Run the git tag command to create a new annotated tag with ID v1.2 for the commit selected in the previous example:

git tag for old commits

git tag -a v1.2 29389857951b64cf874c3557a0f3547bd83b899a

Replacing old tags

Attempting to create a tag with an existing identifier will result in an error. Use the -f (force) option to update an existing tag, which will overwrite its previous content.

git tag replacing old tags

git tag -a -f v1.3 29389857951b64cf874c3557a0f3547bd83b899a

Pushing tags to remote

Tags are not sent automatically with git push — by default git push transfers commits but leaves your tags behind. You have to push them explicitly so that anyone cloning the repository receives them.

To push a single tag, pass its name to git push:

git tag, pushing to remote

git push origin v1.3
Counting objects: 9, done.
Delta compression using up to 5 threads.
Compressing objects: 100% (8/8), done.
Writing objects: 100% (12/12), 2.05 KiB | 0 bytes/s, done.
Total 12 (delta 3), reused 0 (delta 0)
To [email protected]:gr8/gittagdocs.git
* [new tag] v1.3 -> v1.3

To push every local tag that the remote doesn't already have, use the --tags option:

git push all tags

git push origin --tags

Inspecting a tag

Use git show to view the data stored in a tag. For an annotated tag it prints the tag metadata (tagger, date, message) followed by the commit it points to:

git show on an annotated tag

git show v1.3
tag v1.3
Tagger: Jane Doe <[email protected]m>
Date:   Mon Jun 9 14:21:03 2025 +0000

Release version 1.3

commit 29389857951b64cf874c3557a0f3547bd83b899a
Author: Jane Doe <[email protected]m>
Date:   Mon Jun 9 14:18:55 2025 +0000

    Merging branch 'crossword'

Checking out a tag

You can use the git checkout command to inspect a tagged commit. This places the repository in a detached HEAD state — HEAD points directly at a commit instead of a branch. Any new commits you make here will not belong to a branch and will only be reachable through their SHA hash, so they can be lost once you switch away.

git tag, checking out a tag

git checkout v1.3

If you want to keep working from that point, create a branch on the spot:

branch from a tag

git checkout -b release-1.3 v1.3

Deleting tags

You can delete a local tag by passing the -d option and the tag identifier to git tag. See the example below:

git tag, deleting tags

git tag
v1
v2
v3
git tag -d v1
git tag
v2
v3

Deleting a tag locally does not remove it from a remote. To delete a tag from the remote as well, push the deletion:

git delete remote tag

git push origin --delete v1

git log — find the commit you want to tag.
git push — publish your tags to a remote.
git branch — turn a tagged commit into a branch you can build on.

Practice

What are the functionalities and options of the 'git tag' command in Git?

Tags are mutable references that can be changed after being created.Annotated tags store additional metadata such as the tagger's name, email, and date.Lightweight tags are created without the `-a`, `-s`, or `-m` options and do not store additional metadata.The `git tag` command lists all the stored tags in the repository.`git tag` by default creates a tag on the commit referred to by `HEAD`.Using the `-f FORCE` option with `git tag` is necessary to tag an older commit with an existing tag identifier.The `--tags` option with `git push` is used to push several tags together to a remote repository.Using `git checkout` on a tag will put the repository in a separate `HEAD` state, creating a new commit.A tag can be deleted by passing the `-d` option and a tag identifier to the `git tag` command.