How to Delete Remote Git Tags: Importance, Best Practices, and Release Management Tips

In this article, we will know what git tags are, the importance they have in release management, how to delete git tags both remote and local, and the best practices to follow while deleting them.

What is a Git tag?

To know deeply what a tag in Git does, you are required to first understand the importance and  played by branches and commits. A branch has a movable pointer or HEAD pointer that mainly points to the latest commit. A commit captures the code of your software project at a certain time. When you add commits to the branch, its then associated HEAD pointer that automatically moves to point to the latest commit made on that branch.

Now, for you to mark a special version of your project (to mark a commit in a branch), you are required to create a tag.

A tag is usually used to mark the commit on the main/master branch for the software release. Tags can also serve as the future reference for any desired use such as it can cater to reference a stable software project version. Unlike branch HEAD pointers, move as more commits are added to the branch, tags does not move. It remains fixed even if more commits are added.

Types of Git tags

Git has two types of tags:

1. Lightweight tag:

Lightweight tag is the type of tag that does not have extra information apart from the name of the tag and the commit hash that it marks or references. It can be design by utilizing the git tag <tag_name> command.

2. Annotated tag:

Annotated tag is the type of tag that contains extra information such as the tagger’s information like name and email, the date, the commit was tagged, or any message made by the tagger. It can be design by utilzing the git tag -a <tag_name> -m <tag_message>command.

Now that we know how Git tags types, let’s know how to delete them.

How to Delete a local Git tag

In order to delete a local Git tag, use the “git tag” command with the “-d” option.

$ git tag -d <tag_name>

For example, if you wanted to delete a local tag named “v1.0” on your commit list, you would run

$ git tag -d v1.0
Deleted tag 'v1.0' (was 808b598)

If you try to delete a Git tag that does not exist, you will simply be notified that the tag does not exist.

$ git tag -d v2.0
error: tag 'v2.0' not found.

If you want to make sure that tags were correctly deleted, simply list your existing tags using the tag command and the “-l” option.

$ git tag -l
<empty>

Delete a remote Git tag

In order to delete a remote Git tag, use the “git push” command with the “–delete” option and specify the tag name.

$ git push --delete origin tagname

Back to the previous example, if you want to delete the remote Git tag named “v1.0”, you would run

$ git push --delete origin v1.0

To https://github.com/SCHKN/repo.git
 - [deleted]         v1.0

To delete a remote Git tag, you can also use the “git push” command and specify the tag name using the refs syntax.

$ git push origin :refs/tags/<tag>

Back to the example, in order to delete a tag named “v1.0”, you would run

$ git push origin :refs/tags/v1.0

To https://github.com/SCHKN/repo.git
 - [deleted]         v1.0

Why should we specify the “refs/tags”instead of just specifying the tagname?

In some cases, your tag may have the same name as your branch.

If you tried to delete your Git tag without specifying the “refs/tags” you would get the following error

$ git push origin :v1.0

error: dst refspec v1.0 matches more than one.
error: failed to push some refs to '<repository>'

As a consequence, you need to specify that you are actually trying to delete a Git tag and not a Git repository.

• deliverables.

Benefits of deleting tags

Here are some advantages of deleting unused tags:

It helps keep your repository clean and organized by reducing clutter. It ensures that only the needed tags are maintained at every point in time which helps manage relevant tags.

Deleting unused tags eases release management.

It helps prevent eating up storage space, especially on your local machine. Like branches, tags (especially annotated tags which are stored as full objects) consume disk space. Hence, deleting irrelevant tags helps you efficiently utilize your disk space.

Deleting tags can help CI/CD pipelines to be more efficient as only relevant tags will be considered and processed. The performance of the pipeline will improve as old tags won’t be pushed accidentally to trigger it unnecessarily. This will also contribute to faster deployments and deliverables.

Common errors while deleting the tags and how to resolve them

There are some errors you may encounter  when you try to delete a tag. Let’s look at some of them below.

1. Tag deleted keeps coming back even after deletion locally and remotely

You could be in a scenario where you are sure you deleted certain git tags both locally and remotely but you still see them after some time for unknown reasons.

This could happen when you have other collaborators on a git repository. To resolve this, always ensure you communicate the deletion of a tag so that others can update their local repositories. Better still, set up branch protection.

2. Error deleting a tag with the same branch name

error: dst refspec tag_name matches more than one.
error: failed to push some refs to 'https://remote_repository_url'

The error above happens because the tag_name reference is the same name as another reference in the remote repository i.e. there are multiple references (e.g. branches, tags) in the remote repository with the same name you specified.

To resolve the error above, run the command below:

git push origin --delete refs/tags/<tag_name>

This will delete the specified tag_name from the remote repository specified as origin in the above example. Git uses refs/tags/ as a prefix to reference tags.

Alternatively, you can run the command below which does the same thing:

git push origin :refs/tags/<tag_name>

In addition to the errors discussed above, you may have seen other similar errors depending on your scenario.

Frequently Asked Questions 

Q 1: Does deleting a tag also delete a commit?

Ans: Remember that a commit is a snapshot of your software project at a specific time while a tag is simply a reference to that commit.

Internally, when a lightweight tag is created, Git creates a file with the same name as the tag name in the .git/refs/tags directory of your software project. For an annotated tag, Git stores it as an object in the .git/objects directory and also references it in the .git/refs/tags directory with a file that has the same name as the annotated tag created. Regardless of the type of tag being created, i.e. lightweight or annotated, the tag file (for lightweight tags) or tag object (for annotated tags) contains the commit hash that the tag references.

Hence, when you delete a git tag, only the tag is removed. The commit still remains intact.

Q 2: How do you know when to use tags or use branches?

Ans: Branches are used to track progressive development efforts. They are used to develop new features, fix bugs, etc.

Tags are commonly used for releases. They are used to mark a snapshot or version or state of your software project for a software release.

Conclusion

You have learned how tags can be easily deleted to keep a git repository organised and clutter-free. Use tags to manage releases and always audit their usage before deleting them to avoid dependent systems disruption. You can easily delete a tag on your local git repository using the git tag -d tag_name command.

It is recommended you always communicate and perform test runs before deleting a tag to avoid a system breakdown, especially for critical systems.

Use tags appropriately. For example, use tags for releases and use branches to track ongoing development efforts

Also Read Best Kubernetes Alternatives