- Creating a git tag
- Annotated tags
- Lightweight tags
- Tags list
- Tagging old commits
- Replacing old tags
- Pushing the tags to remote
- Checking over tags
- Deleting tags
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.
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
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
Run the code below to list the stored tags:
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 firstname.lastname@example.org: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
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