git tag | Atlassian Git Tutorial (2024)

Creating a tag

To create a new tag execute the following command:

gittag<tagname>

Replace < tagname > with a semantic identifier to the state of the repo at thetime the tag is being created. A common pattern is to use version numbers likegit tag v1.4. Git supports two different types of tags, annotated andlightweight tags. The previous example created a lightweight tag. Lightweighttags and Annotated tags differ in the amount of accompanying meta data theystore. A best practice is to consider Annotated tags as public, and Lightweighttags as private. Annotated tags store extra meta data such as: the tagger name,email, and date. This is important data for a public release. Lightweight tagsare essentially 'bookmarks' to a commit, they are just a name and a pointer to acommit, useful for creating quick links to relevant commits.

Annotated tags

Annotated tags are stored as full objects in the Git database. To reiterate, They store extra meta data such as: the tagger name, email, and date. Similar to commits and commit messages Annotated tags have a tagging message. Additionally, for security, annotated tags can be signed and verified with GNU Privacy Guard (GPG). Suggested best practices for git tagging is to prefer annotated tags over lightweight so you can have all the associated meta-data.

gittag-av1.4

Executing this command will create a new annotated tag identified with v1.4. The command will then open up the configured default text editor to prompt for further meta data input.

gittag-av1.4-m"myversion1.4"

Executing this command is similar to the previous invocation, however, this version of the command is passed the -m option and a message. This is a convenience method similar to git commit -m that will immediately create a new tag and forgo opening the local text editor in favor of saving the message passed in with the -m option.

related material

Git cheat sheet

Check it out

SEE SOLUTION

Learn Git with Bitbucket Cloud

Read tutorial

Lightweight tags

gittagv1.4-lw

Executing this command creates a lightweight tag identified as v1.4-lw. Lightweight tags are created with the absence of the -a, -s, or -m options. Lightweight tags create a new tag checksum and store it in the .git/ directory of the project's repo.

Listing tags

To list stored tags in a repo execute the following:

gittag

This will output a list of tags:

v0.10.0
v0.10.0-rc1
v0.11.0
v0.11.0-rc1
v0.11.1
v0.11.2
v0.12.0
v0.12.0-rc1
v0.12.1
v0.12.2
v0.13.0
v0.13.0-rc1
v0.13.0-rc2

To refine the list of tags the -l option can be passed with a wild card expression:

Tagging old commits

The previous tagging examples have demonstrated operations on implicit commits. By default, git tag will create a tag on the commit that HEAD is referencing. Alternatively git tag can be passed as a ref to a specific commit. This will tag the passed commit instead of defaulting to HEAD. To gather a list of older commits execute the git log command.

$gitlog--pretty=oneline
15027957951b64cf874c3557a0f3547bd83b3ff6Mergebranch'feature'
a6b4c97498bd301d84096da251c98a07c7723e65addupdatemethodforthing
0d52aaab4479697da7686c15f77a3d64d9165190onemorething
6d52a271eda8725415634dd79daabbc4d9b6008eMergebranch'experiment'

Executing git log will output a list of commits. In this example we will pick the top most commit Merge branch 'feature' for the new tag. We will need to reference to the commit SHA hash to pass to Git:

gittag-av1.215027957951b64cf874c3557a0f3547bd83b3ff6

Executing the above git tag invocation will create a new annotated commit identified as v1.2 for the commit we selected in the previous git log example.

ReTagging/Replacing old tags

If you try to create a tag with the same identifier as an existing tag, Git will throw an error like:

fatal:tag'v0.4'alreadyexists

Additionally if you try to tag an older commit with an existing tag identifier Git will throw the same error.

In the event that you must update an existing tag, the -f FORCE option must be used.

gittag-a-fv1.415027957951b64cf874c3557a0f3547bd83b3ff6

Executing the above command will map the 15027957951b64cf874c3557a0f3547bd83b3ff6 commit to the v1.4 tag identifier. It will override any existing content for the v1.4 tag.

Sharing: Pushing tags to remote

Sharing tags is similar to pushing branches. By default, git push will not push tags. Tags have to be explicitly passed to git push.

$gitpushoriginv1.4
Countingobjects:14,done.
Deltacompressionusingupto8threads.
Compressingobjects:100%(12/12),done.
Writingobjects:100%(14/14),2.05KiB|0bytes/s,done.
Total14(delta3),reused0(delta0)
[email protected]:atlasbro/gittagdocs.git
*[newtag]v1.4->v1.4

To push multiple tags simultaneously pass the --tags option to git push command. When another user clones or pulls a repo they will receive the new tags.

Checking out tags

You can view the state of a repo at a tag by using the git checkout command.

gitcheckoutv1.4

The above command will checkout the v1.4 tag. This puts the repo in a detached HEAD state. This means any changes made will not update the tag. They will create a new detached commit. This new detached commit will not be part of any branch and will only be reachable directly by the commits SHA hash. Therefore it is a best practice to create a new branch anytime you're making changes in a detached HEAD state.

Deleting tags

Deleting tags is a straightforward operation. Passing the -d option and a tag identifier to git tag will delete the identified tag.

$gittag
v1
v2
v3
$gittag-dv1
$gittag
v2
v3

In this example git tag is executed to display a list of tags showing v1, v2, v3, Then git tag -d v1 is executed which deletes the v1 tag.

Summary

To recap, Tagging is an additional mechanism used to create a snap shot of a Git repo. Tagging is traditionally used to create semantic version number identifier tags that correspond to software release cycles. The git tag command is the primary driver of tag: creation, modification and deletion. There are two types of tags; annotated and lightweight. Annotated tags are generally the better practices as they store additional valuable meta data about the tag. Additional Git commands covered in this document were git push, and git checkout.Visit their corresponding pages for discussion on their extended use.

Share this article

Next Topic

Git blame