How to delete a git tag

A Git tag is a marker used to point to a specific commit, often used to mark release points, such as v1.0, v2.0, etc. Tags make it easier to find specific versions in a project’s history. However, you might need to delete a tag, like if it was created by mistake or if it’s become stale or redundant.

This guide will walk you through the various scenarios of deleting tags in Git, covering local and remote repositories.

Deleting a local tag

Local tags are tags that exist in your local repository—the version of your project stored on your personal computer.

1. List all tags (optional): To see all of your existing tags, run:

   git tag

   This command lists all of the tags in your local repository, helping you find the name of the tag you want to delete.

2. Delete the tag: To delete a tag locally, use:

   git tag -d <tagname>

   Replace <tagname> with the actual name of the tag you want to delete. The -d flag stands for "delete." This will remove the tag from your local working directory, the place where all of your local files managed by Git are stored on your machine.

Deleting a remote tag

Remote tags are tags that have been pushed to a remote repository. This is the version of your project that is stored on a remote server, accessible to others.

1. Fetch and list all of your remote tags: To view a list of all your tags on your remote repository run the command:

   git ls-remote --tags

   This will give you a list of all your remote tags from the currently configured remote repository.

   If you want to specify a different remote repository from the one that you’re currently tracking you can specify the name of the remote:

   git ls-remote --tags <remote>

2. Delete the tag from remote: To remove a tag from a remote repository, use:

   git push --delete <remote> <tagname>

   Here, <remote> is the name of the remote repository (commonly origin for the default remote) and <tagname> is the name of the tag you wish to delete. The -delete flag tells Git you want to remove the tag from the remote repository.

   This allows you to delete the tag in a single Git command rather than deleting a tag locally, then pushing that change.

Deleting multiple tags

Deleting multiple tags

To delete multiple tags at once, you can use:

git tag -d tag1 tag2 tag3

And for remote tags:

git push origin --delete tag1 tag2 tag3

Deleting all local tags

To delete all local tags:

git tag -d $(git tag -l)

Deleting tags both locally and remotely

You can also delete a tag both from your local repository and the remote repository to ensure consistency.

1. Delete the tag locally using git tag -d <tagname>.

2. Delete the tag from the remote with git push --delete origin <tagname>.

This will push your local tag deletion to the remote repository, ensuring your remote matches the state of your local repository.

Additional Commands and Tips

• Tag not found error: If you try to delete a tag that doesn’t exist, Git will return the error error tag not found. You can check existing tags with git tag again before attempting deletion. Or run git fetch --tags to sync your local repository with your remote repository.

• Deleting tags not on remote: If you have local tags that you haven't pushed to the remote repository and you want to delete them, just follow the local deletion steps. There's no need to involve remote commands for tags that were never pushed.

Best Practices

• Always confirm the tag name and its significance before deleting, especially from remote repositories.

• Notify your team when deleting tags that others may be using or relying on.

For further information on Git tags, see the official Git documentation.