Tagging
This document will discuss the concept of Git tagging and the git tag command. Tags are references that point to specific points in the Git history. Tagging is typically used to capture a point in the history that is used for a flagged version (i.e. v1.0.1). A label is like a branch that doesn’t change. Unlike branches, tags, after being created, have no further history of commits. For more information about branches, visit the git branch page. This document will cover the different types of tags, how to create tags, list all tags, remove tags, share tags, and more.
Creating
a tag
To create a new tag, run the following command:
Replace < tag name > with a semantic identifier to the repository state at the time the tag is created. A common pattern is to use version numbers such as git tag v1.4. Git supports two different types of tags, annotated and lightweight tags. In the previous example, a lightweight label was created. Lightweight tags and annotated tags differ in the amount of metadata that accompanies them. A best practice is to consider annotated tags as public and light tags as private. Annotated tags store additional metadata such as: tagger name, email, and date. This is important data for a public launch. Lightweight tags are essentially “bookmarks” of a confirmation, they are just a name and pointer to a confirmation, useful for creating quick links to relevant confirmations.
Annotated
tags
Annotated tags are stored as complete objects in the Git database. To reiterate, they store additional metadata such as: the name of the tagger, the email and the date. Similar to confirmations and confirmation messages Annotated labels have a tagging message. In addition, for security, annotated tags can be signed and verified with GNU Privacy Guard (GPG). The suggested best practices for git tagging is to prefer annotated tags over lightweight ones so you can have all the associated metadata.
Running this command will create a new annotated tag identified with v1.4. The command will open the default text editor configured to prompt for more metadata input.
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 past message with the -m option.
Light tags
Running this command creates a light tag identified as v1.4-lw. Lightweight labels 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 repository.
Listing tags
To list tags
stored in a repository, run the following
: This
will generate
a list of tags: To refine the tag list, the -l option can be passed with a wildcard expression: This previous example uses
the -l option and a wildcard expression
of -rc
that returns a list of all tags marked with a -rc prefix. It is traditionally used to identify launch candidates.
Tagging old
receipts Previous tagging examples have demonstrated operations on implicit confirmations. By default, git tag will create a tag on the commit referenced by HEAD. Alternatively, the git tag can be passed as a reference to a specific commit. This will label the passed commit instead of default in HEAD. To collect a list of previous commits, run the git log command.
Running git log will generate a list of commits. In this example, we will choose the ‘feature’ of the most confirmed merge branch for the new tag. We’ll need to reference the commit SHA hash to move to Git:
Running the previous git tag invocation
will create a new annotated commit identified as v1.2 for the commit we selected in the git log example above.
Relabeling/Replacing old tags
If you try to create a tag with the same identifier as an existing tag, Git will throw an error like: Also
, if you try to tag a previous commit with an existing tag ID,
Git will generate the same error
.
In the event that you need to update an existing tag, the -f FORCE option must be used
.
Running the above command will map the acknowledgment 15027957951b64cf874c3557a0f3547bd83b3ff6 to tag identifier v1.4. Override any existing content for the v1.4 tag.
Share: Sending
tags to
remote sharing tags is similar to inserting branches. By default, git push will not insert tags. Tags must be explicitly passed to git push.
To push multiple tags simultaneously, pass the -tags option to the git push command. When another user clones or pulls a repository, they receive the new tags.
Check out tags
You can view the status of a repository on a tag by using the git checkout command
.
The above command will remove the v1.4 tag. This places the repository in a separate HEAD state. This means that the changes you make will not update the label. They will create a new separate commitment. This new separate commit will not be part of any branch and will only be directly accessible via the SHA commits hash. Therefore, it is a best practice to create a new branch each time you make changes to a separate HEAD state.
Delete tags
Removing tags
is a simple operation. Passing the -d option and a tag identifier to the git tag will remove the identified tag.
In this example, the git tag is executed to display a
list of tags that display v1, v2, v3, then the git -d v1 tag is executed which removes the v1 tag
.
Summary To
recap, tagging is an additional mechanism used to create a snapshot of a Git repository. Tagging is traditionally used to create semantic version number identifier tags that correspond to software release cycles. The git tag command is the main driver of the tag: create, modify, and delete. There are two types of tags; Annotated and lightweight. Annotated tags are generally best practices as they store additional valuable metadata about the tag. Additional Git commands covered in this document were git push and git checkout. Visit their corresponding pages to discuss their widespread use.