How Do You Rename a Git Tag?

Better Stack Team
Updated on July 25, 2024

To rename a Git tag, you need to delete the existing tag and create a new tag with the desired name. Git does not provide a direct command to rename tags, but you can achieve it with a sequence of commands:

Steps to Rename a Git Tag

  1. Delete the Existing Tag: Delete the tag you want to rename. This does not affect any commits; it only removes the tag reference.

     
    git tag -d <old-tag-name>

    Replace <old-tag-name> with the name of the tag you want to rename.

    Example:

     
    git tag -d v1.0.0

  2. Create a New Tag: Create a new tag with the desired name at the same commit or any other commit.

     
    git tag <new-tag-name> [<commit-SHA>]

    Replace <new-tag-name> with the new name you want to assign to the tag. Optionally, specify <commit-SHA> if you want to tag a specific commit (if omitted, it defaults to HEAD).

    Example:

     
    git tag v2.0.0

    Or, to tag a specific commit:

     
    git tag v2.0.0 abc1234

  3. Push the New Tag to Remote (if needed): If you've already pushed the old tag to a remote repository, and you want to push the new tag with the same name:

     
    git push origin :refs/tags/<old-tag-name>    # Delete old tag from remote
git push origin <new-tag-name>                # Push new tag to remote

    Replace <old-tag-name> with the old tag name and <new-tag-name> with the new tag name.

    Example:

     
    git push origin :refs/tags/v1.0.0
git push origin v2.0.0

Notes

  • Collaboration: Renaming tags can cause issues if others have already pulled the old tag. It's recommended to communicate changes with your team to avoid confusion.
  • Local Changes: After renaming the tag locally, make sure to update any scripts or documentation that reference the old tag name.
  • History Preservation: Deleting and recreating a tag changes its history. It's generally not recommended to modify tags that have been shared with others unless necessary.

Example Scenario

Let's say you want to rename tag v1.0.0 to v1.1.0:

 
# Delete old tag locally
git tag -d v1.0.0

# Create new tag locally
git tag v1.1.0

# Push new tag to remote (assuming v1.0.0 was already pushed)
git push origin :refs/tags/v1.0.0
git push origin v1.1.0

This sequence of commands effectively renames the Git tag v1.0.0 to v1.1.0. Adjust the commands as per your specific requirements and collaboration needs.

Got an article suggestion? Let us know
Explore more
Git
Licensed under CC-BY-NC-SA

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.