In Git, tagging is a way to put a permanent, human-friendly label on a specific commit.

Think of it as saying:

“This commit is important. Call it v1.0.0.”

Tags are most commonly used for releases (v1.0.0, v2.1.3, etc.), but you can tag any commit you want to mark.

What a tag actually is

A branch name (like main) moves forward as you add new commits.

A tag is different: it points to a single commit and never moves unless you explicitly change it.

Even if you add more commits after D, the tag v1.0.0 always points to D.

The git tag Command

The git tag command is used to create tags that serve as snapshots of your repository at specific points in time. Tags are often associated with significant releases, making them invaluable for version control.

Creating Tags with git tag

To create a tag, you simply use the git tag command followed by the name of the tag. For example:

This command creates a lightweight tag named v1.0.0 at the current commit. Lightweight tags are simply pointers to a commit, without any additional metadata.

Tagging with Messages

While lightweight tags are useful, you can also create annotated tags that include a message. Annotated tags are stored as full objects in the Git database and can contain additional information like the tagger’s name, email, and date.

To create an annotated tag, use the -a flag and -m for a message:

This command creates an annotated tag and associates it with the current commit. Annotated tags help provide context for why a specific version was released, which is beneficial for both your future self and collaborators.

Viewing Existing Tags

After creating tags, you may want to see what tags exist in your repository. The command for this is straightforward:

This command lists all tags in alphabetical order. If you want to view tags that match a specific pattern, you can pass a filter to the command:

This will display only the tags that start with v1., making it easy to find specific versions.

Viewing Tag Details

For detailed information about a specific tag, especially annotated tags, you can use the git show command:

This command outputs the commit that the tag points to, along with the tag message and any other relevant information. Understanding what a tag represents is crucial for effective version management.

Lightweight vs Annotated Tags

Lightweight Tags

Lightweight tags in Git are essentially references to specific commits in your repository. Unlike annotated tags, which store additional metadata, lightweight tags are simple pointers.

When you create a lightweight tag, Git records the commit it points to, but does not include information such as the tagger's name, email, or date.

Basic Command Structure

Example:

Annotated Tags

Annotated tags are essentially full objects in the Git database. They contain more information than lightweight tags, making them suitable for marking official releases. When you create an annotated tag, Git generates a new object that includes:

This structure allows you to have a richer context for each tag, which is particularly helpful when reviewing project history or when multiple team members are working on the same codebase.

Creating an annotated tag is straightforward. You can use the git tag command with the -a flag followed by a message using the -m flag. Here’s how you can create an annotated tag:

In this example, v1.0 is the tag name, and the message describes the purpose of the tag. You will notice that once you create this tag, it will include all the metadata we discussed earlier.

Tagging Best Practices

Creating tags is straightforward, but following best practices ensures they serve their purpose effectively. Here are some practical guidelines:

Semantic Versioning

Adopting a versioning scheme like Semantic Versioning can simplify understanding your project's progress. Semantic versioning uses a three-part version number: MAJOR.MINOR.PATCH. For example, a tag of v2.3.1 indicates the second major version, third minor update, and first patch.

Consistency

Maintain consistency in your tagging strategy. Use the same format for all tags and apply them at consistent points in your development workflow, like after major features or bug fixes have been completed.

Documentation

Document your tagging process, including the criteria for creating tags and their meanings. This information helps new team members understand your project’s history and the significance of each tag.

Using Tags in Collaboration

Tags play a critical role when collaborating with others on a project. They provide a clear reference for stable points in your codebase, making it easier for teams to understand which versions are stable or ready for production.

Pull Requests and Releases

When creating pull requests for new features, it’s often beneficial to indicate which tag the work pertains to. For example, if a feature is targeted for v1.2.0, reference that tag in the pull request description. This clarity helps reviewers understand the context and the intended release.

Continuous Integration

In continuous integration (CI) workflows, tags can trigger deployments. For instance, you may configure your CI system to deploy code automatically when a new tag is created:

This approach ensures that only tagged versions, which are typically stable, are deployed to production environments.

Advanced Tagging Scenarios

While basic tagging is useful, advanced scenarios can further enhance your workflow.

Tagging Older Commits

You can also tag commits that are not the latest. To do this, specify the commit hash:

This command allows you to create a tag for a specific point in your project’s history, which is especially useful for tracking down bugs in older releases.

Moving Tags

Sometimes, you might need to move a tag to a different commit. First, delete the existing tag locally:

Then, recreate the tag at the desired commit:

Sharing Tags

When you push changes to a remote, tags do not get pushed automatically. Use the following command to push a specific tag:

To push all tags at once, use:

This is useful to ensure that everyone on the team has the same set of tags and can reference them appropriately.