Creating a Git tag

Description

Tags are references showing particular points in a Git history. The main function of tagging is to capture a point in a Git history that marks version release. Tags don’t change. After a tag is created, it has no history of commits

Creating a Git tag

In order to create a Git tag you need to run the command below:

git tag <name-of-tag>

While the tag is being created put a semantic identifier to the state of the repository instead of <name-of-tag>. There are two kinds of tags that are supported by Git: annotated and lightweight tags. A difference between these two tags is the amount of metadata they store. Another difference is that annotated tags are public and lightweight tags are private.

Annotated tags

Git database store these tags as full objects. Some additional metadata are stored in annotated tags. These can be the tagger name, email, and date. Annotated tags include a tagging message, as it is in case of commits. They can be additionally signed and verified with GPG (GNU Privacy Guard) for security purposes.

Running the command below, you can create a new annotated tag with v1.3 id. The configured default text editor will then show up prompting for further meta data input.

git tag -a v1.3

Lightweight tags

The command below creates a lightweight tag identified as v1.3-lw. They are created without the -a, -s, or -m options. Lightweight tags generate a new tag checksum stored it in the .git/ directory.

git tag v1.3-lw

Tags list

Run the code below to list the stored tags:

git tag

As a result, you will have this 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 clear up the list of tags:

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 mentioned by HEAD. It can be passed as a ref to a particular commit. As a result, the passed commit will be tagged instead of defaulting to HEAD. Run the git log command to output a list of older commits: In the example below, the Merge branch 'feature'commit is used for a new tag. For passing to Git, the SHA hash have to be referenced to your commit:

git log --pretty=oneline
29389857951b64cf874c3557a0f3547bd83b899s Merging branch 'crossword'
b4g5697498bd301d84096da251c98a07c7723e65 init method for crossword
89f3gaab4479697da7686c15f77a3d64d9165190 little changes in logic
3hy4a271eda8725415634dd79daabbc4d9b6008e Merging branch 'how-it-works'

Run the git tag command for generating a new annotated commit with v1.2 ID for the commit that has been selected in the previous example:

git tag -a v1.2 29389857951b64cf874c3557a0f3547bd83b899s

Replacing old tags

In the case of trying to tag an older commit with an existing tag identifier, an error will occur. You should use -f FORCE option for updating an existing tag. It will cancel any existing content for the tag identifier.

git tag -a -f v1.3 29389857951b64cf874c3557a0f3547bd83b899s

Pushing tags to remote

In order to push several tags together, you should pass the --tags option to git push command, and if another user clones a repository, they will get the new tags.

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 git@github.com:gr8/gittagdocs.git
* [new tag] v1.3 -> v1.3

Checking over tags

With the help of the git checkout command, you can check the state of a repo. This command will put the repo in a separate HEAD state. As a result, instead of updating the tag, the changes will create a new separate commit, which will not be a part of any branch. This commit will only be accessible by the SHA hash.

git checkout v1.3

Deleting tags

You can delete a tag bypassing the -d option and a tag identifier to the git tag. You can find an example of this operation below:

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