How to Delete Remote and Local Tags on Git (The Definitive Guide)

On Git, you can use tags to mark commits that are more important than others. You can use git tags to mark releases, bug fixes, or just to inform other developers with notes to a commit. The most typical use case for tags is to tie them into product releases.

In Git, you can delete a tag with the git tag -d command:

git tag -d <tag-name>

To remove the tag from the remote repo, you need to run git push –delete origin <tag-name>

git push --delete origin <tag-name>

This guide teaches you how to delete tags both locally and remotely. You will learn how to remove a tag that has the same name as a branch. Besides, you’ll see three concrete examples of removing tags from Git.

Let’s jump into it!

Deleting a Local Tag on Git

To remove a local tag on Git, run the git tag command with the -d option which stands for delete.

git tag -d <tag-name>

Example

Let’s see a concrete example of removing a tag.

Inside my example project, I have three tags. Let’s list the tags with the git tag command:

$ git tag

Now, let’s delete the first tag, “v1.0” by running the git tag -d command on it:

$ git tag -d v1.0

Now, let’s list the tags again:

$ git tag

Now the tag called v1.0 is gone. But it still exists in the remote origin.

The next section shows how to get rid of the remote tags too.

Deleting a Remote Tag on Git

When dealing with Git tags, you don’t add or commit them as you do with other changes in the project.

This means deleting a local tag has no impact on the remote tags you might have. In other words, you need to run a separate command to remove the remote tags from your project.

git push --delete origin <tag-name>

This deletes a tag with the <tag-name> from the remote repo. But notice that this command doesn’t specifically target tags. You can run this command to remove a remote branch as well.

Sometimes, you might have a tag that has the same name as another branch. In this case, you cannot use the above command to delete the tag because the command doesn’t know whether you want to remove the branch or tag.

In this case (and in other cases too) it’s wiser to use this command to remove the remote tags:

git push origin :refs/tags/<tag>

This way you cannot accidentally delete a branch or get an error when the branch has the same name as a tag.

Example 1: Delete a Tag from the Remote

Let’s see a concrete example to support understanding.

Here are the remote tags of my example project on Git:

You can also see these by running the following command:

$ git ls-remote -t origin

Now, let’s get rid of the v1.0 tag in the remote repo:

$ git push --delete origin v1.0
To https://github.com/artturijalli/exampleProject.git
 - [deleted]         v1.0

This deletes the tag v1.0 from the remote.

Example 2: Delete a Tag with the Same Name as a Branch

Let’s see another concrete example of deleting a remote tag in the case where we have a branch with the same name as the tag.

In my case, I have a tag called feature and a branch called feature.

Let’s verify this by checking what’s on the remote:

 $ git ls-remote      
From https://github.com/artturijalli/exampleProject.git
42442b0f66b992b06c004af2ac41578d49a45e10	HEAD
8772787ba8f708756214e9703629cd127d67debd	refs/heads/feature
42442b0f66b992b06c004af2ac41578d49a45e10	refs/heads/main
42442b0f66b992b06c004af2ac41578d49a45e10	refs/heads/new-code-changes
6b5c8ad92df253f42c56cc8aba296ae194ccf0a1	refs/pull/1/head
42442b0f66b992b06c004af2ac41578d49a45e10	refs/tags/feature
3448575bb8d0779aa3f459c45503827456f87bba	refs/tags/v2.0
3448575bb8d0779aa3f459c45503827456f87bba	refs/tags/v3.0

The refs/tags/feature means there’s a tag called feature. The refs/heads/feature means there’s a branch called feature as well.

Now, let’s try to remove the remote feature tag.

 $ git push --delete origin feature 
error: dst refspec feature matches more than one
error: failed to push some refs to 'https://github.com/artturijalli/exampleProject.git'

The error says it all. There are two things named feature in the remote so it doesn’t know what to remove. Because the command doesn’t specifically target tags, it doesn’t know what to do so it throws an error.

In this case, let’s remove the tag with the other variant of git push command you learned earlier:

 $ git push origin :refs/tags/feature 
To https://github.com/artturijalli/exampleProject.git
 - [deleted]         feature

Now the removal was successful!

Summary

Today you learned how to remove tags on Git.

To take home, you can use the git tag -d <tag> command to remove a local tag. To remove a remote tag, use the git push origin :refs/tags/<tag> command.

Thanks for reading. Happy coding!

Read Also

How to Delete a File on Git

About the Author

Artturi Jalli
I'm an entrepreneur and a blogger from Finland. My goal is to make coding and tech easier for you with comprehensive guides and reviews.