Git Create Tag Guide

August 10, 2022

Introduction

Git tags are highlights in project development used to denote specific points in the project's history. Tags usually mark a feature release but can also indicate commits.

Git tags are similar to Git branches, except no changes can be made to a tag after creation.

In this tutorial, you will learn to create tags in Git.

Learn to create tags in Git.

Prerequisites

Note: Bare Metal Cloud servers integrate perfectly with GitHub development using Bare Metal Cloud GitHub Actions. Choose a preconfigured server instance and automate your software development project.

What Are Tags in Git?

Git tags represent specific reference points in a software development project's history. Use Git tags to mark a commit and highlight it for future reference.

You can tag any commit but typically users tag release versions. For example, a tag can mark a project's initial stable version, such as v1.0. Once a tag is created, it includes all the changes made to the project and it acts as a git branch that doesn't change. Git tags are excellent for comparing commits.

Note: See how to create and manage a Git tag with a release status.

How to Create a Tag in Git?

There are two types of Git tags:

  • Annotated tags. They contain metadata about the user creating the tag, such name, email address, and date.
  • Lightweight tags. Does not contain any additional metadata. It just points to a commit.

The sections below explain how to create each type of tag in Git, as well as how to relate a tag to a commit.

Creating an Annotated Tag

Annotated tags are usually used for public releases as they contain detailed metadata about the tagger and an optional message about the commit.

Create an annotated tag by specifying the -a flag with the git tag command:

git tag -a [tag name]

For [tag name], specify the name of the tag. While there are no limitations for setting a tag name, the best practice is to follow semantic versioning and name the tag as follows:

v[major].[minor].[patch]
  • [major]. The current public version number; modifications aren't compatible with previous versions.
  • [minor]. The current functional release. The modifications are compatible with previous versions.
  • [patch]. An increment for bug fixes or patches that don't impact overall software functionality.

For example:

git tag -a v1.2

The command creates a new annotated tag identified as v1.2. The configured default text editor then opens to prompt for a tag description:

Adding a message to an annotated Git tag.

Alternatively, use the -m flag to add a message right away instead of prompting. For example:

git tag -a v1.5 -m "Release v1.5 created"
Creating an annotated Git tag with a message.

The command creates the tag with the provided message.

Creating a Lightweight Tag

A lightweight tag doesn't contain any additional metadata found in annotated tags.

Create a lightweight tag when the release isn't public, and you need private or temporary labels with only basic tag information. Some Git commands for naming objects, such as git describe, ignore lightweight tags by default.

Create a lightweight tag using the following syntax:

git tag [tag name]

For example:

Creating a lightweight Git tag.

The command creates a new Git tag named v1.0.

Note: If you are just starting out with Git, follow our Git beginner's guide.

Create Git Tag For a Commit

Create a Git tag for a particular commit from Git history by specifying the commit SHA. Obtain the commit SHA by running:

git log --oneline
obtaining the commit SHA

After obtaining the commit SHA, create a tag using the following syntax:

git tag [tag name] [commit SHA]

For example:

Create a Git tag for a particular commit

The command creates a tag for the specified commit in your Git history.

Push Tags to Remote Repository

The git push command doesn't automatically push the tags to a remote repository. To make the local tags available in a remote repository, specify the --tags flag:

git push --tags
Pushing Git tags to the remote repository.

The command pushes all local tags to the connected remote repository.

Alternatively, to push a specific tag to a remote repository, use the following syntax:

git push [tag name]

How to View Tags in Git?

To view all Git tags, run the following command:

git tag
Viewing all existing tags in Git.

The command outputs all the tags created in the project, listed in alphabetical order. If the tag list is long, search the tag names by specifying the -l flag and outputting only the tags for a specific version.

For example:

git tag -l "v1.2*"
Listing only specific Git tags.

The output contains only the tags starting with v1.2. Check out our Git List Tags guide to learn more about listing git tags from local or remote repositories.

Note: Refer also to our guide on how to clone git tags.

Conclusion

This tutorial showed how to create annotated and lightweight Git tags for your project. For more Git guides, check out how to rename tags in Git, revert the last commit, resolve merge conflicts in Git, or restore a deleted repository.

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 Commands Cheat Sheet
March 10, 2020

This article lists out all the important Git commands every developer will need at some point. For future reference, it includes...
Read more
How to Delete a Git Branch Remotely and Locally
October 13, 2020

This article provides an overview of commands for deleting local and remote Git branches.
Read more
How To Unstage Files on Git
September 15, 2020

Unstaging in Git means removing queued changes from the index. This guide covers several different ways to unstage changes.
Read more
How To Rename a Local and Remote Git Branch
April 11, 2024

Git is a VCS that helps you control software development. This guide shows commands...
Read more