Table of Contents
Introduction to git tags
Git uses tags to identify different release histories of a repository.
Git tag is the command responsible for creating tags within a git project. Tags have similar behaviour to git branches. They are identified using unique refs upon creation. However, they do not keep history as the git branches do. Git allows the creation of multiple tags on a branch or different branches. There exist two different types of git tags which are lightweight tags and the annotated git tags. The main distinction between these two tags is the amount of information or metadata they store.
Annotated git tags usually contain detailed information like the date created, the tag creator and email. They are therefore best utilized for working with public repositories. On the other hand, lightweight tags serve only as identifiers to a particular commit. You can use them in private projects as bookmarks or quick links to commit histories.
In this tutorial about tags, we will explain how to create tags, access tags and how to delete tags in an active repository.
Git tag syntax
Below is a basic syntax to use git tag. To get the complete list of supported arguments and options, please follow the official git documentation.
$ git tag <tag name>
Understanding how to work with tags
The image below shows the distribution of tags within different branches in a working repository.
According to the image, several tags are distributed on master, bug-fix and feature branches in a project. The master branch has two tags v1.2 and v2.4 the feature branch has two tags V2.2 and V3.1 and lastly, the bug-fix branch has one tag v1.0.
You therefore can create tags at different production points depending on the kinds of assignment you are handling.
Setting up the lab environment
It's essential that you first set up a lab environment before you can start to work on a git project. We will clone
tagging remote project to our local working station windows 10 pro for practice. I will also be using git version 2.32.0.windows.2 to communicate between the remote project
tagging and my local copy.
You should see the following sample output after running the
git clone command.
$ git clone https://github.com/Maureen-Mulombi/tagging.git
Now that the lab environment is ready, we will practice how to create a git tag in the next section using examples.
Different methods to create tags
Method-1: Create a new tag using the tag name
You can create a new tag by calling the specific tag name in the tag function as follows;
First, we shall create a new branch
feature from the master branch which we will use in this example to create a new tag. It’s always advisable to create a new local branch to work with apart from the master branch to keep clean codes and to avoid confusion.
$ git checkout -b feature Switched to a new branch 'feature'
Next, we will now create a tag
v1.0 on the
feature branch using
git tag <tag name> command as shown below:
$ git tag v1.0
We will then run the
git tag command to view the newly created tag :
$ git tag v1.0
We have successfully created a lightweight tag
v1.0. What if you would like to make an annotated tag?
The procedure for creating an annotated tag is similar although, we will have to modify the tag function as follows:
$ git tag -a <tag-name> <"message">
-a represent the annotation while
–m option is for adding a message to the specific tag. You can think of this in a similar way to when creating a commit with a message.
We shall proceed to create an annotated tag as follows:
$ git tag -a v2.0 -m "my version 2.0"
Next, we will run
git tag –n command to view the annotated tag v2.0 as demonstrated below:
$ git tag -n v1.0 Initial commit v2.0 my version 2.0
You will notice that the
git tag –n option command gives more details of the committed tags unlike running the
git tag command without the –n option.
Method-2: Create a new tag from a git commit
You can create a new tag (lightweight) from a commit using the
git tag <tag_name> <commit- id> command.
In this example, however, we are going to create an annotated tag using
git tag -a <tag_name> <commit- id> -m <"message"> command as illustrated below:
For this exercise, we will use the
feature branch again. First, we will run the
git log --oneline command to view the available commits.
$ git log --oneline b9f0d58 (HEAD -> feature) tgafile-two 2eaeede tagfile 9627449 (tag: v2.0, tag: v1.0, origin/master, origin/HEAD, master) Initial commit
Next, we will create an annotated tag
v3.0 from the second commit
2eaeede as demonstrated below:
$ git tag -a v3.0 2eaeede -m "annotated tag example" $ git tag -n v1.0 Initial commit v2.0 my version 2.0 v3.0 annotated tag example
From the output upon running the
git tag -n command we managed to create a new annotated tag
Lastly, we will run
git log --oneline command to confirm the commit
2eaeede changed to a tag.
$ git log --oneline b9f0d58 (HEAD -> feature) tgafile-two 2eaeede (tag: v3.0) tagfile 9627449 (tag: v2.0, tag: v1.0, origin/master, origin/HEAD, master) Initial commit
Method-3: Create a new tag from the git last commit
You can create a new tag from the last commit using the
HEAD option in the tag function as follows:
$ git tag <tag_name> HEAD
feature branch as the active branch we shall proceed as displayed below:
$ git tag v3.1 HEAD $ git tag v1.0 v2.0 v3.0 v3.1
To confirm that the tag was created from the last commit
b9f0d58 of the
feature branch we shall run the
git log –oneline command.
$ git log --oneline b9f0d58 (HEAD -> feature, tag: v3.1) tgafile-two 2eaeede (tag: v3.0) tagfile 9627449 (tag: v2.0, tag: v1.0, origin/master, origin/HEAD, master) Initial commit
We have the last commit
b9f0d58 turned into a tag as shown in the results.
How to checkout a tag in git
You can checkout a specific tag using the
git checkout <tag-name> command as follows:
While on the active branch
feature we will checkout tag
$ git checkout v3.0 Note: switching to 'v3.0'. You are in 'detached HEAD' state. You can look around, make experimental changes and commit them, and you can discard any commits you make in this state without impacting any branches by switching back to a branch. If you want to create a new branch to retain commits you create, you may do so (now or later) by using -c with the switch command. Example: git switch -c <new-branch-name> Or undo this operation with: git switch - Turn off this advice by setting config variable advice.detachedHead to false HEAD is now at 2eaeede tagfile
Here git issues a warning that we are now in a detached head and we may lose any commit we make at this point if we do not switch to a new branch. Therefore, if we wish to still keep the checked out tag
v3.0 the best option is to create a new branch using
git switch -c <new-branch-name> command.
How to push tags upstream
For you to push your tags to remote the default
git push command will not work as it does for the branches. You will therefore require to modify the
git push option to include tags as follows;
$ git push --tags Enumerating objects: 8, done. Counting objects: 100% (8/8), done. Delta compression using up to 4 threads Compressing objects: 100% (6/6), done. Writing objects: 100% (7/7), 727 bytes | 242.00 KiB/s, done. Total 7 (delta 1), reused 0 (delta 0), pack-reused 0 remote: Resolving deltas: 100% (1/1), done. To https://github.com/Maureen-Mulombi/tagging.git * [new tag] v1.0 -> v1.0 * [new tag] v2.0 -> v2.0 * [new tag] v3.0 -> v3.0 * [new tag] v3.1 -> v3.1
Good job as you now have your tags updated in the remote repository
How to delete a tag in git
You can delete a tag as follows:
First, you will run the
git tag command while in the active branch.
$ git tag v1.0 v2.0 v3.0 v3.1
Next, select the tag to delete and apply the
git tag –d <tag-name> command as follows:
In this case, we shall delete tag
$ git tag -d v2.0 Deleted tag 'v2.0' (was a325820)
We have covered the following topics about tags:
- Introduction to git tags
- Different methods to create tags in git
- How to checkout a tag
- How to push tags
- How to delete tags