How do you rename a Git tag?

Question

Today I was looking through the logs for a project and realized that I fat fingered a tag name some time ago. Is there some way to rename the tag? Google hasn't turned up anything useful.

I realize I could check out the tagged version and make a new tag, I even tried that. But that seems to create a tag object that isn't quite right. For one,

git tag -l

lists it out of order relative to all of the other tags. I have no idea if that's significant, but it leads me to believe that the new tag object isn't quite what I want. I can live with that, because I really only care that the tag name matches the documentation, but I'd rather do it "right", assuming there is a right way to do this.

Answer

Here is how I rename a lightweight tag old to new:

git tag new old           # Create a new local tag named `new` from tag `old`.
git tag -d old            # Delete local tag `old`.
git push origin new :old  # Push `new` to your remote named "origin", and delete
                          #     tag `old` on origin (by pushing an empty tag
                          #     name to it).

The colon in the push command removes the tag from the remote repository. If you don't do this, Git will create the old tag on your machine when you pull. Finally, make sure that the other users remove the deleted tag. Please tell them (co-workers) to run the following command:

git fetch --prune --prune-tags

Note that if you are renaming an annotated tag, you need to ensure that the new tag name is referencing the underlying commit and not the old annotated tag object that you're about to delete. If the old tag is an annotated tag, or you aren't sure, you can use ^{} to dereference the object until a non-tag object is found:

# create a new annotated tag "new" referencing the object
# which the old annotated tag "old" was referencing:
git tag -a new old^{}

How can I fix the Git error "object file ... is empty"?

Git branch command behaves like 'less'