Git Rename Tag Guide

August 11, 2022

Introduction

Git tags are specific reference points in a Git project history. Each tag has a unique name, usually referencing a release version. However, sometimes a Git tag needs to be renamed if the name doesn't follow semantic versioning rules or if the tag name is incorrect.

In this tutorial, you will learn to rename a tag in Git.

Learn to rename tags in Git.

Prerequisites

How to Rename a Tag in Git?

Renaming a tag in Git involves creating a new tag and deleting the old one. Renaming a tag in a remote repository requires additional steps compared to renaming a local one. Follow the steps below to rename a Git tag.

Step 1: Create New Tag

Depending on the type of tag you want to rename, create a new lightweight or annotated tag:

Lightweight Tags

Use the following syntax to create a new lightweight tag in place of the old one:

git tag [new_tag_name] [old_tag_name]

For example:

git tag v1.7 v1.6
Renaming a lightweight Git tag.

The command replaces the old lightweight tag (v1.6) with the new one (v1.7).

Annotated Tags

The syntax for renaming an annotated tag is:

git tag -a [new_tag] [old_tag]^{} -m [new_message]

For example:

git tag -a v1.7 v1.6^{} -m "Version 1.7 released"
Renaming an annotated Git tag.

The command replaces the v1.6 tag with v1.7 and adds the new message to the annotated tag.

Note: The above command works for both lightweight and annotated tags. Since annotated tags are objects, the command ensures that the new tag points to the underlying commit and not to the old annotated tag object you want to delete. Lightweight tags aren't considered as objects.

Step 2: Delete the Old Tag

Clean up the local repository by deleting the old tag. If the tag has been pushed to the remote repository, you need to delete the tag from there as well.

Delete Tag in Local Repository

Use the following syntax to delete a tag in the local repository:

git tag -d [old_tag_name]

For example:

git tag -d v1.6
Deleting a Git tag in a local repository.

The command removes the old tag from the local repository.

Note: See how to restore a repository if you delete it by mistake.

Delete Tag in Remote Repository

If a tag has been pushed to a remote repository, remove the tag to prevent Git from recreating the old tag when making a pull request.

Use the following syntax to do so:

git push origin [new_tag_name] :[old_tag_name]

For example:

git push origin v1.8 :v1.7
Renaming a tag in a remote repository.

The colon removes the old tag (v1.7) from the remote repository, replacing it with the new one (v1.8).

Note: See how to checkout a Git tag to mark and reference release versions properly.

Step 3: Ensure Other Users Clean Their Repository

Your collaborators may still have the old tag in their local repositories. Ensure that they run the following command to clean up their repositories and implement any tag changes you have made:

git pull --prune --tags

Conclusion

This tutorial showed how to rename lightweight and annotated Git tags in a local and remote repository.

For more Git tutorials, see how to work with Git tag releases, checkout Git tags, Git prune command or learn to use Git with our Git beginner's guide.

Was this article helpful?
YesNo
Bosko Marijan
Having worked as an educator and content writer, combined with his lifelong passion for all things high-tech, Bosko strives to simplify intricate concepts and make them user-friendly. That has led him to technical writing at PhoenixNAP, where he continues his mission of spreading knowledge.
Next you should read
Git Fetch: Definition & Examples
December 8, 2021

The git fetch command helps retrieve new contents from a remote repository, without applying the changes immediately. Follow this guide to learn how to use git fetch.
Read more
Git Tag Release Management
December 29, 2021

A Git release is a GitHub object created from Git tags that helps show official program versions on your project page. Learn how to work with Git releases and manage them in this guide.
Read more
What Is Git Bash; Working with Git Bash Commands
September 8, 2021

Git Bash lets you manage your code and repository using a command-line interface on Windows. Learn how to use Git Bash effectively.
Read more
How To Resolve Merge Conflicts in Git
June 16, 2021

Joining information from multiple sources sometimes yields merge conflicts. Learn about how they happen and how to resolve merge conflicts.
Read more