keepcalculator

06 Numbers and Powers

Delete Git Tag: When and How to Remove It

Card No. 06·81848 · Updated · Standard formula, shown below

Yes, you can delete a git tag, and the exact command depends on whether the tag is local or remote. Deleting a tag removes its pointer to a specific commit without altering the commit history itself.

What a Git Tag Is

A git tag is a named reference to a specific commit, typically used to mark release points (v1.0, v2.3, etc.). Unlike branches, tags do not move as new commits are added. There are two types:

  • Lightweight tags: just a pointer to a commit, stored in refs/tags/.
  • Annotated tags: stored as objects with a message, tagger name, and date. They are created with git tag -a or git tag -s for signed tags.

Deleting a tag only removes that reference; the commit it pointed to remains in the repository and can be reached by other refs or by its SHA.

Deleting a Local Tag

To delete a tag in your local repository, use:

git tag -d <tagname>

For example, to delete a tag called v1.0:

git tag -d v1.0

The -d flag stands for delete. If the tag exists, Git prints Deleted tag 'v1.0'. If it doesn’t, you get an error like error: tag 'v1.0' not found.

Deleting a local tag has no effect on remote repositories. If you previously pushed the tag, it still exists on the remote until you delete it there too.

Deleting a Remote Tag

To delete a tag from a remote repository (e.g., on GitHub, GitLab, or Bitbucket), use:

git push origin --delete <tagname>

Or the older syntax:

git push origin :refs/tags/<tagname>

For example:

git push origin --delete v1.0

This removes the tag from the remote. Other users who have fetched the tag will still have it locally until they delete it themselves.

If you want to delete a tag from a remote that you don’t have locally, you can still use the same command; Git will match the remote ref.

Deleting All Local Tags That Match a Pattern

Sometimes you need to delete multiple tags, for example all tags matching a release pattern. You can combine git tag -l with xargs:

git tag -l 'v1.*' | xargs git tag -d

This lists all tags starting with v1. and deletes each one. Be careful with the pattern; test with git tag -l 'v1.*' first to see what will be deleted.

For remote tags, you can loop through the list:

git tag -l 'v1.*' | xargs -I {} git push origin --delete {}

This is a destructive operation, so double-check the pattern.

When You Should Delete a Tag

Deleting a tag is appropriate in several situations:

  • Mistaken tag: you tagged the wrong commit and want to move the tag to a different commit. You can delete and recreate, or use git tag -f to force-move it.
  • Release rollback: a release was tagged but later found broken, and you want to remove the tag to avoid confusion.
  • Cleanup: you have many stale or temporary tags (e.g., build tags) that are no longer needed.
  • Renaming: you need to rename a tag, which is done by creating a new tag and deleting the old one.

Deleting a tag does not affect branches or commits. The commit remains in history and is still reachable by its SHA or by any branch that contains it.

Common Problems and Misconceptions

One common mistake is thinking that deleting a tag deletes the commit. It does not. The commit object remains in the repository and will still be visible in logs if referenced by a branch or another tag.

Another issue: if you delete a remote tag, other users who have fetched it will still have the tag locally until they fetch with pruning. To remove deleted remote tags from your local repository, use:

git fetch --prune --prune-tags

This removes local tags that no longer exist on the remote.

If you try to delete a tag that you don’t own on a remote, you’ll get an error. You need write access to the repository.

Also note that annotated tags and signed tags are deleted the same way as lightweight tags; the object is removed from the refs, but the underlying tag object may remain in the object database until garbage collection runs.

Deleting Tags vs. Deleting Branches

Tags and branches are both refs, but they behave differently. Deleting a branch removes the branch pointer and, if no other ref points to the commits, they become unreachable and may be garbage collected. Deleting a tag only removes the tag pointer; the commit it pointed to is still reachable if any branch or other tag points to it, or if you know the SHA.

Because tags are meant to be permanent, many teams never delete tags except for corrections. If you need to move a tag, prefer to delete and recreate it with the correct commit, and force-push the new tag to the remote.

Frequently Asked Questions

How do I delete a tag that has already been pushed to GitHub?

Use git push origin --delete <tagname> to remove it from the remote. Then delete it locally with git tag -d <tagname> if you haven’t already.

What happens to the commit when I delete a tag?

Nothing happens to the commit. It remains in the repository. If no other branch or tag points to it, it becomes unreachable and may eventually be removed by garbage collection, but it is not immediately deleted.

Can I delete a tag that is not the latest?

Yes, you can delete any tag, regardless of its position in history. Tags are independent references.

How do I delete all tags that match a pattern on the remote?

List the tags with git tag -l 'pattern', then loop through them with xargs git push origin --delete. For example: git tag -l 'v1.*' | xargs -I {} git push origin --delete {}.

Why is my deleted tag still showing up after I fetch?

Because your local repository still has the tag. Run git fetch --prune --prune-tags to remove local tags that were deleted on the remote.

Can I recover a deleted tag?

If you know the commit SHA, you can recreate the tag with git tag <tagname> <sha>. If you don’t know the SHA, check the reflog or ask a teammate who might still have the tag locally.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →