Git tags tutorial: complete guide to version control tagging

I recently went through a major update cycle across all the themes, refactoring code for reusability, cleaning up dependencies, updating framework versions, and implementing some significant redesigns. But here’s the thing: I wanted my customers to still have access to the stable versions they were using before these big changes rolled out.

That’s when Git tags became essential. Whether you’re building web applications, libraries, desktop software, or mobile apps, keeping track of changes across versions is crucial for any development project. Git tags provide a simple yet powerful way to mark important milestones in your codebase and create reliable reference points for releases.

This post covers everything you need to know about Git tags: what they are, how to use them effectively, and why they should be part of your development workflow.

What are Git tags?

A Git tag is a reference to a specific commit in your repository’s history. Unlike branches, tags don’t move—they mark a snapshot of your project at a particular point in time.

Developers typically use tags to mark:

Official release versions (e.g. v1.0.0, v2.1.3)
Major or minor updates (v2.1, v3.0-beta)
Important milestones in development
Stable points before major refactoring
Production deployments

Lightweight vs annotated tags

Git supports two types of tags, each with different use cases:

Lightweight tags

These are simple pointers to a commit—no message, no metadata.

git tag v1.0.0

Best for:

Internal versioning
Quick temporary markers
Personal reference points

Annotated tags

These are full Git objects that include metadata like the author, date, and message.

git tag -a v1.0.0 -m "Initial stable release with core features"

Best for:

Public releases
Production versions
Official milestones
Any tag that others will reference

Recommendation: Use annotated tags for anything that might be shared or referenced by others.

Creating and managing tags

Creating Tags

# Create an annotated tag for the current commit
git tag -a v1.2.0 -m "Added user authentication and dashboard"

# Create a tag for a specific commit
git tag -a v1.1.0 9fceb02 -m "Bug fixes and performance improvements"

# Create a lightweight tag
git tag v1.0.0-beta

Pushing Tags to Remote

Tags aren’t automatically pushed with regular commits:

# Push a single tag
git push origin v1.2.0

# Push all tags at once
git push origin --tags

# Push all tags (including lightweight ones)
git push origin --follow-tags

Viewing and managing tags

List and Filter Tags

# List all tags
git tag

# List tags with their messages
git tag -n

# Filter tags (e.g., all v2 releases)
git tag -l "v2.*"

# Show detailed tag information
git show v1.2.0

Deleting Tags

# Delete a tag locally
git tag -d v1.5.0

# Delete a tag from remote repository
git push origin --delete v1.5.0

# Delete multiple tags locally
git tag -d v1.0.0 v1.1.0 v1.2.0

Working with tagged versions

Checking Out a Tag

# View code from a specific version
git checkout v1.2.0

This puts you in a detached HEAD state. If you need to make changes:

# Create a new branch from the tag
git checkout -b hotfix-v1.2.0 v1.2.0

Comparing Tags

# See differences between two tags
git diff v1.0.0 v1.2.0

# List commits between tags
git log v1.0.0..v1.2.0 --oneline

Best practices for Git tags

1. Use semantic versioning

Follow the MAJOR.MINOR.PATCH format:

MAJOR: Breaking changes
MINOR: New features (backward compatible)
PATCH: Bug fixes

git tag -a v2.1.3 -m "Security patch for authentication module"

2. Write descriptive tag messages

# Good
git tag -a v1.3.0 -m "Added REST API endpoints and improved error handling"

# Less helpful
git tag -a v1.3.0 -m "Version 1.3.0"

3. Tag consistently

Establish a tagging convention for your project:

When to create tags (every release, major milestones, etc.)
Naming scheme (v1.0.0, release-1.0.0, 1.0.0)
What information to include in tag messages

4. Don’t move tags

Once pushed, avoid deleting and recreating tags as others may depend on them.

Common use cases

Release management

# Mark a stable release
git tag -a v2.0.0 -m "Major release: New UI and improved performance"

# Create a release candidate
git tag -a v2.0.0-rc1 -m "Release candidate for version 2.0.0"

Deployment tracking

# Tag deployments to production
git tag -a deploy-prod-2025-07-28 -m "Production deployment - July 28, 2025"

Milestone marking

# Mark project milestones
git tag -a milestone-beta -m "Beta version ready for testing"

Why Git tags matter

Git tags provide several key benefits:

Reliable Reference Points: Easily return to any version of your code
Release Management: Track what’s in production vs. development
Collaboration: Team members can reference specific versions
Automation: CI/CD systems can trigger on tag creation
Documentation: Clear history of project evolution
Rollback Safety: Quick way to revert to known-good versions

Git tag command reference

# Creating tags
git tag v1.0.0                              # Lightweight tag
git tag -a v1.0.0 -m "Release message"      # Annotated tag
git tag -a v1.0.0 9fceb02 -m "Message"      # Tag specific commit

# Viewing tags
git tag                                     # List all tags
git tag -l "v2.*"                          # Filter tags
git show v1.0.0                            # Show tag details
git tag -n                                 # List tags with messages

# Managing tags
git push origin v1.0.0                     # Push single tag
git push origin --tags                     # Push all tags
git tag -d v1.0.0                          # Delete local tag
git push origin --delete v1.0.0            # Delete remote tag

# Working with tags
git checkout v1.0.0                        # Checkout tag
git checkout -b branch-name v1.0.0         # Create branch from tag
git diff v1.0.0 v2.0.0                     # Compare tags

Start incorporating Git tags into your workflow today—your future self (and your team) will thank you for the clear project history and reliable version management.

/Michael Andreuzza