How do I edit an existing tag message in Git?

We have several annotated tags in our Git repository. The older tags have bogus messages that we would like to update to be in our new style.

% git tag -n1
v1.0 message
v1.1 message
v1.2 message
v2.0 Version 2.0 built on 15 October 2011.

In this example, we would like to make v1.x messages look like the v2.0 message. How would we do this?

git tag <tag name> <tag name>^{} -f -m "<new message>"

This will create a new tag with the same name (by overwriting the original).

To update a complex message, just specify the annotated tag option with -a or the signed tag option with -s:

git tag <tag name> <tag name>^{} -f -a

This will open an editor with the contents of your old tag message.

git tag <tag name> <tag name>^{} -f -a

This is an improvement: without ^{} it will create a new tag object that reference the old tag object, where both of them will have the same tag name.

<tag name>^{} will resolve the tag/reference until it finds the first commit hash.

TL;DR

You can do this by deleting your tag and recreating it while spoofing the date and author:

> git tag -d <tag-name>
> [GIT_COMMITTER_DATE=<original-commit-date>] \
> [GIT_AUTHOR_NAME=<original-author-name>] \
> git tag <tag-name> [commit]

Whole story:

Building on Sungram's answer (originally proposed as an edit):

1. Accepted answer

This is an improvement over Andy and Eric Hu's answers. Their answers will create a new tag object that references the old tag object and both are going to have the same name.

To illustrate this, consider the following:

> git tag tag1 tag1 -f -a  # accepted answer
> git rev-list --objects -g --no-walk --all
[ example output: ]
6bdcc347fca041a5138f89fdf5276b3ebf9095d5
260ab7928d986472895b8c55e54569b3f3cb9517 tag1
a5797673f610914a45ef7ac051e3ee831a6e7c25 tag1
f22d6308c3cd330a3b0d86b9bf05562faf6b6f17

> git show tag1
tag tag1
Tagger: [tagger]
Date:   [date of updated tag]
[Updated description]

tag tag1
Tagger: [tagger]
Date:   [date of original tag]
[Original description]

[tagged commit details]

2. Sungram's improvement

Using <tag name>^{} as the second argument of git tag will instead delete all previous tags with the same name.

Consider the continuation of the previous terminal session:

> git tag tag1 tag1^{} -f -a  # suggested improvement
> git rev-list --objects -g --no-walk --all
[ example output: ]
6bdcc347fca041a5138f89fdf5276b3ebf9095d5
75f02acacfd7d91d55b5bcfdfb1f00aebeed15e3 tag1
f22d6308c3cd330a3b0d86b9bf05562faf6b6f17 

> git show tag1
tag tag1
Tagger: [tagger]
Date:   [date of updated tag]
[Updated description]

[tagged commit details]

3. Save the date

Lastly, if you want to keep the date of the original tag as the date of the updated tag, use some awk (or similar) magic or just paste the date you want instead. The following is a substitute for the second example (otherwise the original date would be lost due to overriding):

> GIT_COMMITTER_DATE="$(git show tag1 |                              # get info about the tag cascade including the date original of the original tag
> awk '{
>     if ($1 == "Date:") {
>         print substr($0, index($0,$3))
>     }
> }' |                                                               # extract all the dates from the info
> tail -2 | head -1)"                                               `# get the second to last date, as the last one is the commit date` \
> git tag tag1 tag1^{} -a -f                                         # finally, update the tag message, but save the date of the old one
>
> git rev-list --objects -g --no-walk --all
6bdcc347fca041a5138f89fdf5276b3ebf9095d5
e18c178f2a548b37799b100ab90ca785af1fede0 tag1
f22d6308c3cd330a3b0d86b9bf05562faf6b6f17
> git show tag1
tag tag1
Tagger: [tagger]
Date:   [date of original tag]
[Updated description]

[tagged commit details]

References:

• SO: Quick listing objects in git database

• SO: Change the committer date of a git tag

• Awk: A tutorial and introduction

• SO: Filter output by first-token-of-line and extract rest-of-line with awk

• SO: How to put bash line comment in a multi-line command

4. DIY

Alternatively to updating the tags, you can just delete them and create them again. As it turns out updating just adds a new tag and makes it point to the old one, or alternatively, just implicitly deletes the old one and creates a new one to point to the same commit anyway.

You can achieve this by issuing:

> git tag -d <tag-name>
> [GIT_COMMITTER_DATE=<original-commit-date>] \
> [GIT_AUTHOR_NAME=<original-author-name>] \
> git tag <tag-name> [commit]

Here [optional] is an optional field; <required> is a required field. Of course, you can add any flags after the git tag command that you normally would.

@Andy 's solution as present in 2016

git tag <tag-name> <tag-name> -f -a

is wrong. After it, with

git show

command, we will see stack tags with same name.

It add a new tag with same tag name and new message at commit <tag-name>. But it don't remove old tag. It's a special case of this command:

git tag [<commit> | <old-tag>] <tag-name>

But just <old-tag> is same with <tag-name>.

---

Correct solution is simple, just update tag is OK.

git tag <tag-name> -f -a

Remember, only ONE here.

If we want change tag, which isn't HEAD, we need an extra <commit> argument.

git tag <commit> <tag-name> -f -a

> we would like to make v1.x messages look like the v2.0 message

With Git 2.17 (Q2 2018), there will be an alternative to creating a new tag with git tag <tag name> <tag name> -f -m "<new message>", since "git tag" learned an explicit "--edit" option that allows the message given via "-m" and "-F" to be further edited.

See commit 9eed6e4 (06 Feb 2018) by Nicolas Morey-Chaisemartin (nmorey).
^{(Merged by Junio C Hamano -- gitster -- in commit 05d290e, 06 Mar 2018)}

> ## tag: add --edit option > > Add a --edit option which allows modifying the messages provided by -m or -F, the same way git commit --edit does.

You will have to tag again, using the -f force flag.

git tag v1.0 -f -m "actual message"

Using the answers above (especially Sungam's), this is my alias one-liner for .gitconfig. Replaces existing tag and preserves the commit date.

[alias]
tm = "!sh -c 'f() { export GIT_COMMITTER_DATE=$(git log -1 --format=%ci $0); git tag -f -a $0 $0^{}; }; f '"

Improvements?

If you are using a GUI like smartgit just

1. create the same tag again at the same position with the new message
2. choose "overwrite existing tag"
3. force-push the tag to the upstream repository

Here's a set of aliases that should do it for you based on the existing answers (especially stanm's) here:

# Edit an existing tag, preserving the date and tagger
tag-amend = "!f() { : git tag ;\
    eval \"`git x-tag-environment-string`\";\
    git tag -a -f --edit -m \"$(git x-tag-message \"$1\")\" \"$1\" \"$1^{}\" \"${@:2}\";\
}; f"

# Rewrite an existing tag, preserving the date and tagger (accepts -m and -F)
tag-rewrite = "!f() { : git tag ;\
    eval \"`git x-tag-environment-string`\";\
    git tag -a -f \"$1\" \"$1^{}\" \"${@:2}\";\
}; f"

# Helpers to Extract the Tag Data
x-tag-data = tag -l --format
x-tag-message = x-tag-data '%(contents)'
x-tagger-name = x-tag-data '%(taggername)'
x-tagger-email = x-tag-data '%(taggeremail)'
x-tag-date = x-tag-data '%(taggerdate:rfc2822)'
x-tag-environment-string = "!f() { echo '\
    export GIT_COMMITTER_DATE=${GIT_COMMITTER_DATE-`git x-tag-date \"$1\"`};\
    export GIT_COMMITTER_NAME=${GIT_COMMITTER_NAME-`git x-tagger-name \"$1\"`};\
    export GIT_COMMITTER_EMAIL=${GIT_COMMITTER_EMAIL-`git x-tagger-email \"$1\"`};\
';}; f"

These aliases accept a single tag name and any other flags to git tag and can be modified to support name changes pretty easily as well.

Usage:

# opens editor to edit existing message
git tag-amend <tag name>

# add a new paragraph to the existing message
git tag-amend <tag name> -m "<new paragraph>"

# replace the message with a new one
git tag-rewrite <tag name> -m "<new message>"

Support for light-weight tags

Use creatordate, creatorname, and creatoremail instead of the tagger... variants. The creator... shortcuts will use tagger... if it exists and fallback to committer....