git tag

Description

Tags are references pointing to particular commits in Git history. The main function of tagging is to capture a specific point in history, typically to mark a version release. Tags are immutable; once created, they do not track commit history.

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. Git supports two kinds of tags: annotated and lightweight. The main difference between them is the amount of metadata they store.

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. They can also be signed and verified using GPG (GNU Privacy Guard) for security purposes.

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

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

To push a tag to a remote repository, pass the tag name to the git push command. This ensures that other users cloning the repository will receive the new tag.

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

Checking over tags

You can use the git checkout command to inspect a tagged commit. This places the repository in a detached HEAD state. Any new commits made here will not belong to a branch and will only be accessible via their SHA hash.

git tag, checking over tags

git checkout v1.3

Deleting tags

You can delete a 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

Practice