git tag usage explained for beginners [Easy Examples]

 

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

Sample Output:

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  v3.0.

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

Using the 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 v3.o.

$ 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 tagging .

 

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 v2.0.

$ git tag -d v2.0
Deleted tag 'v2.0' (was a325820)

 

Summary

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

 

Further reading

Git-tag