Rename a Git tag without confusing its target or annotation

Git has no dedicated tag-renaming command. Create the new tag at the intended object, verify it, then remove the old ref if that is appropriate. For a tag that marks a commit, peel the old tag to its commit explicitly.

Create the replacement locally

For a lightweight replacement:

git tag new-name 'old-name^{commit}'

For a new annotated tag, use this alternative:

git tag -a new-name 'old-name^{commit}' -m "Release under the corrected name"

Do not run both creation commands for the same new name. Replace old-name and new-name with your actual tags, then check their commit targets:

git rev-parse 'old-name^{commit}'
git rev-parse 'new-name^{commit}'
git show new-name

git tag new-name old-name without peeling can point the new ref at an existing annotated tag object. That retains the object's old internal tag name and annotation; it does not rename that object. A freshly annotated tag has new tagger metadata and the message you supply. A signed tag must be signed again if you create a new tag object.

Update the remote deliberately

Publish the new tag before removing the old one:

git push origin refs/tags/new-name:refs/tags/new-name
# After verifying the replacement and deciding the old name should disappear:
git push origin :refs/tags/old-name
git tag -d old-name

Fully qualified refs avoid ambiguity with a branch of the same name. Server rules may reject deletion. These commands do not remove old tag refs already stored in other clones.

Treat published tags as release identifiers

Builds, downloads, documentation, and hosting-platform release records may depend on the old name. A new tag does not automatically migrate those references or release metadata. When consumers already use a tag, publishing a corrected new tag while retaining the old identifier is often less disruptive than deleting it.

FAQ

What if the tag points at the wrong commit?

An unpublished local tag can be recreated after verifying the right commit. For a published tag, prefer a new name; replacing the old ref is a coordinated history change, not a routine force push. Other users may retain the previous object under that name.

Can the original annotation be preserved exactly under a new name?

The tag name is part of an annotated tag object. Reusing that object preserves its old name; creating a properly named object changes it and invalidates any old signature. Copy the intended message and sign the new object if required.

Can I rename many tags?

Script an explicit old-to-new mapping, verify collisions and targets first, and separate creation from deletion. A bulk text substitution can create invalid names or unintentionally rename release identifiers.

See git-tag and git-push.