Git

How to delete tags locally and remotely in Git

It’s the 2nd quarter of the year, and you and your team have built lots of exciting features to be launched this quarter. You, as the release manager, are prepping for the next release by collaborating with other teams. You have to ensure a smooth and successful release process that includes reviewing and identifying old release tags that are no longer relevant and need to be deleted to maintain a clean and organized repository.

In this article, we’ll discuss what tags are, the role they play in release management, how to delete them, and the best practices to follow when deleting them.

Key Takeaways

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. Use tags for releases and use branches to track ongoing development efforts.

Try the Git Remote Repository Lab for free

What is a git tag?

To understand what a tag in Git does, you need to first understand the roles played by commits and branches. A commit captures the code changes of your software project at a specific time. A branch has a movable pointer(HEAD pointer) that points to the latest commit. When you add more commits to a branch, its associated HEAD pointer automatically moves to point to the latest commit made on that branch.

Now, for you to mark a specific version of your project (i.e., to mark a commit in a branch), you need to create a tag.

A tag is commonly used to mark a commit on the main or master branch for a software release. Tags can serve as a future reference for any desired use, e.g., they can serve as a reference for a stable software project version. Unlike branch HEAD pointers that move as more commits are added to a branch, a tag does not move. It remains fixed even if more commits are added, as visualized below:

Above, the tag, v1.0.0, marks the commit, 04378d6. Also, the tag didn’t move, even if more commits (i.e., dab43d6, 2d07abe, and 80cb9ce) were made on the master branch.

Git has two types of tags:

Lightweight tag: as the name implies, this type of tag does not have extra information apart from the name of the tag and the commit hash that it references or marks. It can be created using the git tag <tag_name> command.
Annotated tag: this type of tag contains extra information like the tagger’s information (name and email), the date when the commit was tagged, and any message made by the tagger. It can be created using the git tag -a <tag_name> -m <tag_message> command.

Now that we know how Git tags work let’s dive into how to delete them.

How to delete local git tags

You can see a list of your repository's release tags using the git tag -n or git show --tags command. You can view an existing tag’s information using the git show <tag_name> command. To exit the git show command after viewing the tag, type 'q’.

Now, let’s go ahead to see how to delete old tags from your local git repository. Below is the syntax of the command for deleting a local git tag:

git tag -d <tag_name>

Below is an example demonstrating how to delete multiple local tags using one command.

git tag -d example_tag_1 example_tag_2

The command above will delete the example_tag_1 and example_tag_2. All that’s needed to accomplish this is single spacing between the tag names.

The -d option is an alias for --delete.

How to delete remote git tags

You also probably have old tags that exist on the remote git repository. You can view a list of those tags using the git ls-remote --tags <remote_repo_alias> command.

Let’s now see how to delete these remote tags. These two methods can be used to delete remote git tags:

Method 1:

Below is a syntax of the command that can be used to delete a remote git tag:

Git push <remote_repo_alias> --delete <tag_name_1> <tag_name_n>

Below is an example demonstrating how to delete multiple remote tags using one command.

git push origin --delete example_tag_1 example_tag_2

The command above will delete the remote tags with the names example_tag_1 and example_tag_2, on the remote repo aliased as origin.

Method 2:

Another way of deleting a remote tag is to use a command following the syntax below:

Git push <remote_repo_alias> :refs/tags/<tag_name>

Below is an example demonstrating how to use the command:

git push origin :refs/tags/example_tag_1

The command above deletes the specified tag name, example_tag_1 from the remote repository aliased as origin. Git uses refs/tags/ as a prefix to reference tags.

Best practices when deleting tags

Below are the best practices to adhere to when deleting tags:

It is important to communicate and run tests before the deletion of a tag to avoid service disruptions or breakdowns of the dependent downstream systems.
You should always document the removal of a tag. The documentation acts as a reference for newly onboarded or existing team members to understand why it was deleted and what steps were taken to ensure critical systems were not affected.
Regularly review and clean up irrelevant tags to maintain a clean and organized repository and reduce clutter.
Depending on the industry for which the software is built, tags could be very important for compliance validation. Before deleting these kinds of tags, you should back them up first for future reference.
Use branch protection settings on remote git hosting platforms to restrict who can actually push new tags to the remote repository.

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 when deleting a tag and how to fix them

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

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.

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. Feel free to comment below if you encounter any errors we have not covered in this article.

FAQ

Below are some frequently asked questions about deleting tags:

Does deleting a tag also delete a commit?

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.

How do you know when to use tags or use branches?

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, version, or state of your software project for a software release.

Master Git with our Git for Beginners course:

Conclusion

You have learned how tags can be easily deleted to keep a git repository organized and clutter-free. Use tags to manage releases and always audit their usage before deleting them to avoid dependent systems disruption. Lastly, follow the best practices discussed in this article to efficiently manage tag deletion.

Joy Ada Uche

May 30, 2023 • 7 min read