Last modified: January 27, 2025

This article is written in: 🇺🇸

Creating and Managing Git Tags

Tags in Git provide a convenient way to reference specific points in your repository’s history. They are often used to mark important milestones, such as release versions (e.g., v1.0, v2.0). Unlike branches, which continue to move forward as new commits are added, tags are static references tied to a particular commit.

Creating Tags

Lightweight Tags

Lightweight tags are essentially just pointers to a commit. They contain only the tag’s name and the commit reference. These are quick to create and are often used for internal or temporary tagging.

Creating a Lightweight Tag for a Specific Commit

I. Get the commit hash (for example, b4d373k8990g2b5de30a37bn843b2f51fks2b40).

II. Run:

git tag <tag-name> <commit-hash>

Example

If you want to create a tag named v2.0 that points to the commit with hash b4d373k8990g2b5de30a37bn843b2f51fks2b40, you would run:

git tag v2.0 b4d373k8990g2b5de30a37bn843b2f51fks2b40

Creating a Lightweight Tag Using a Commit Reference

You don’t always need the raw commit hash. You can use a branch name or even a commit message (if it’s unique enough to be recognized):

git tag <tag-name> <branch-name>
git tag <tag-name> "<commit-message>"

Examples

Tag the latest commit on the master branch with v2.0:

git tag v2.0 master

Tag a commit with the message "Fix bug in login form" with v2.0:

git tag v2.0 "Fix bug in login form"

Annotated Tags

Annotated tags store additional metadata, including the tagger’s name, email, date, and a message. They are recommended when you want to keep a more descriptive record of why the tag was created or who created it.

To create an annotated tag, use the -a flag and include a message (-m):

git tag -a <tag-name> -m "<tag-message>"

Example

git tag -a v2.0 -m "Release version 2.0 with major feature updates"

When you run the above command, Git creates an annotated tag named v2.0. You can later use git show v2.0 to view the commit, tag message, tagger info, and date.

Viewing Tags

To list all tags in your repository, simply run:

git tag

You’ll get a list of all tags:

v1.0
v1.1
v2.0
...

To view more information about a specific tag, including the commit details and the annotated tag message (if it’s an annotated tag), use:

git show <tag-name>

Example

git show v2.0

This displays the commit at which v2.0 is pointing, the tagger’s name, email, date, and any message associated with the tag.

Pushing Tags to a Remote Repository

Pushing All Tags

By default, regular git push commands do not push tags. To push all tags from your local repository to the remote, use:

git push --tags

This will synchronize your local tags with the remote repository, allowing other collaborators to access them.

Pushing a Specific Tag

If you only want to push a particular tag:

git push origin <tag-name>

Replace <tag-name> with the exact name of the tag you wish to push.

Tags vs Branches

While both tags and branches are references to commits, they serve different purposes:

I. Mutability

• Branches move as new commits are added (they are effectively pointers that always refer to the tip of a series of commits).
• Tags are immutable references to a specific commit (they do not move once created).

II. Use Cases

• Branches are used for ongoing development (e.g., feature branches, hotfix branches).
• Tags are used to mark a specific milestone (e.g., a versioned release).

In other words, if you want to mark a precise moment in history—like a deployed release—you use a tag. If you want to develop or maintain code over time, you use a branch.

Good Practices for Tagging

• Use annotated tags to include metadata like author, date, and messages, making them more informative and useful for releases or significant milestones.
• Ensure tag names are meaningful by following conventions like v1.0, v2.0.1, or release-2023-08-15, so the purpose of the tag is immediately clear.
• Include descriptive messages in annotated tags to document changes or the significance of the release, providing context for the tag.
• Always push tags to the remote repository to ensure they are accessible to other team members and any integrated CI/CD systems.