Tagging Releases: How to Use Git Tags for Version Control

Previously in this course, we covered Squashing Commits: Clean Up Your Git History Like a Pro to keep our project history readable. Now that we have a clean commit history, it's time to mark specific milestones as formal versions.

In software development, your commit history is a continuous stream of changes. However, when you share your code with others or deploy to a server, you need a way to say, "This specific snapshot is version 1.0.0." That is exactly what a git tag is for.

What is a Git Tag?

A tag is a permanent, immutable pointer to a specific commit in your history. While branches move forward as you add new commits, a tag stays locked to the exact state of your code at the moment it was created.

Think of it like a bookmark in a book. Even if you write more chapters (commits) later, the bookmark stays exactly where you placed it. We use tags to define releases, making it easy to identify exactly what code is running in production, a concept we explore further when discussing Blue-Green Deployment Concept: Achieving Zero-Downtime Releases.

Creating a Lightweight Tag

There are two types of tags: lightweight and annotated. For most beginner workflows, a lightweight tag is simply a pointer.

To create a tag for the current commit, run:

Bash
git tag v1.0.0

If you want to tag a specific historical commit, you need its hash (which you learned how to find in our Best Practices for Commit Messages: A Guide for Developers lesson):

Bash
git tag v1.0.0 <commit-hash>

You can verify your tags exist by running git tag without any arguments.

Pushing Tags to GitHub

By default, Git does not push tags to the remote repository when you run git push. This is a security feature to prevent you from accidentally sharing internal tags.

To push a single tag to your remote repository:

Bash
git push origin v1.0.0

If you have created multiple tags locally and want to push them all at once, use:

Bash
git push origin --tags

Hands-on Exercise

Let’s apply this to our running project. Follow these steps to mark your current progress as a release:

1. View your commit history and pick the hash of your last stable commit.
2. Create a lightweight tag named v0.1.0 pointing to that commit.
3. Push that tag to your origin repository.
4. Go to your repository on GitHub and click the "Tags" tab (usually found near the branch dropdown) to see your new release marker.

Common Pitfalls

• Forgetting to push: Remember that git push only sends branches. If you don't explicitly push your tags, your team won't see them on GitHub.
• Moving a tag: Once a tag is pushed, it is considered "public" and immutable. If you accidentally tag the wrong commit, you have to delete the local tag (git tag -d v1.0.0), delete the remote tag (git push --delete origin v1.0.0), and recreate it. Avoid this by double-checking your commit hash before tagging.
• Confusing Tags with Branches: Remember, branches are for development (they change), while tags are for releases (they should not change).

FAQ

Can I modify a tag after I create it? Technically yes, but you shouldn't. Once a tag is shared with others, changing it causes confusion for anyone who has already pulled your code.

What is an annotated tag? An annotated tag is stored as a full object in the Git database and contains a message, the tagger's name, and the date. Use git tag -a v1.0.0 -m "Initial release" to create one.

Do I need a specific naming convention? Yes. Most developers use Semantic Versioning (SemVer), which follows the MAJOR.MINOR.PATCH format (e.g., v1.2.3).

Recap

Tags allow you to create immutable snapshots of your project history. By using git tag to label your releases and git push origin <tag> to sync them to GitHub, you create a clear, traceable history of your software's evolution. This practice is essential for any professional workflow, as it provides a clear reference point for debugging or rolling back if a release goes wrong.

Up next: Handling Sensitive Data.