Semantic versioning with tags in Git - Commands & Configuration

Introduction

Semantic versioning helps you label your software versions clearly using numbers like 1.0.0. Git tags let you mark these versions in your project history so you can easily find or share them later.

When you want to mark a stable release of your project so others know which code is safe to use

When you need to track changes between versions with clear version numbers like 1.0.0, 1.1.0, or 2.0.0

When you want to share a specific version of your code with teammates or users

When you want to roll back to a previous version quickly if a new release has problems

When you want to automate deployment tools to use the latest tagged version

Commands

This command creates an annotated tag named v1.0.0 with a message describing the release. Annotated tags store extra info like the tagger's name and date.

Terminal

git tag -a v1.0.0 -m "Release version 1.0.0"

Expected Output

No output (command runs silently)

→

-a - Creates an annotated tag

→

-m - Adds a message to the tag

This command pushes the tag v1.0.0 to the remote repository so others can see and use this version.

Terminal

git push origin v1.0.0

Expected Output

Total 0 (delta 0), reused 0 (delta 0)

To https://github.com/username/repo.git

 * [new tag]         v1.0.0 -> v1.0.0

This command lists all tags in your local repository so you can see all version labels you have created.

Terminal

git tag

Expected Output

v1.0.0

This command switches your working directory to the code state at the tag v1.0.0, letting you view or use that exact version.

Terminal

git checkout v1.0.0

Expected Output

Note: switching to 'v1.0.0'.



You are in 'detached HEAD' state. You can look around, make experimental changes and commit them, and you can discard any commits you make in this state without impacting any branches by switching back to a branch.



HEAD is now at abc1234 Commit message for v1.0.0

Key Concept

If you remember nothing else from this pattern, remember: semantic version tags in git let you mark and share exact versions of your code clearly and safely.

Common Mistakes

Creating lightweight tags instead of annotated tags

Lightweight tags do not store extra information like who created the tag or when, making them less useful for releases.

Always use 'git tag -a' with a message for release versions to create annotated tags.

Not pushing tags to the remote repository

Tags stay only in your local repository and others cannot see or use them until pushed.

Use 'git push origin <tagname>' to share tags with others.

Using inconsistent tag naming without semantic versioning format

It becomes hard to understand the order and meaning of versions without a clear pattern like MAJOR.MINOR.PATCH.

Follow semantic versioning format like v1.0.0, v1.1.0, v2.0.0 for clarity.

Summary

Use 'git tag -a v1.0.0 -m "message"' to create an annotated semantic version tag.

Push tags to remote with 'git push origin v1.0.0' so others can access them.

List tags with 'git tag' and checkout a version with 'git checkout v1.0.0' to use that code state.