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.

Make your mark

Join the writer's program

Are you a developer and love writing and sharing your knowledge with the world? Join our guest writing program and get paid for writing amazing technical guides. We'll get them to the right readers that will appreciate them.

Write for us
Writer of the month
Marin Bezhanov
Marin is a software engineer and architect with a broad range of experience working...
Build on top of Better Stack

Write a script, app or project on top of Better Stack and share it with the world. Make a public repository and share it with us at our email.

community@betterstack.com

or submit a pull request and help us build better products for everyone.

See the full list of amazing projects on github