Git Tagging

Introduction & Overview

Mark releases with Git tags: lightweight versus annotated, why push ignores tags, deleting them safely, tagging older commits and semantic-versioned releases.

What a Tag Is

A tag is a named reference to a specific commit. Teams often use tags to mark releases such as v1.0.0, v1.1.0, or prod-2026-07-14.

Unlike branches, tags normally do not move. They point to an exact moment in history.

Tip: Use tags to mark important milestones such as production releases, stable demos, or compliance snapshots.

Lightweight vs Annotated Tags

Git supports two common tag types.

A lightweight tag is just a simple name pointing to a commit.

This is quick and useful for personal or temporary markers.

An annotated tag stores extra metadata such as the tagger name, date, and message.

Annotated tags are generally better for official releases.

git tag v1.0.0

Listing Tags

To filter by a pattern:

This is useful when a repository has many releases.

git tag

Tagging Older Commits

You do not have to tag only the latest commit. First find the commit ID:

Then tag that specific commit:

This is common when teams forget to tag a release at the time it happened.

git log --oneline

Pushing Tags to a Remote

Tags do not automatically go to the remote when you push a branch.

If your deployment pipeline uses tags as release triggers, this step is essential.

git push origin v1.0.0

Deleting Tags

Be careful when removing release tags because other systems or teammates may rely on them.

git tag -d v1.0.0

Checking Out a Tag

You can inspect the repository at a tagged release:

This usually places you in detached HEAD state because you are on a commit, not a branch.

If you want to make changes starting from that tag, create a branch:

Note: Checking out a tag is excellent for reproducing a past release, testing an older version, or debugging a regression.

git checkout v1.0.0

Release Example

A simple release workflow could look like this:

Now the code and the release marker are both available remotely.

git switch main
git pull
git tag -a v2.0.0 -m "Release version 2.0.0"
git push origin main
git push origin v2.0.0

When to Use Each Tag Type

Use lightweight tags when:

Use annotated tags when:

What You Should Remember

Tags mark important commits. Lightweight tags are simple pointers, while annotated tags carry release-friendly metadata. Tags are not pushed automatically, so remember to send them to the remote when needed. When checking out a tag, be aware of detached HEAD and create a branch if you plan to continue working.

For real release workflows, annotated tags are usually the better choice.

Test Your Understanding

Scenario: Your team is creating an official v2.0.0 release and wants tag metadata plus a message.

Question: Which kind of tag from the tutorial is the better fit?

Choose the tag type that stores release-friendly metadata and a message.

Scenario: You created v2.0.0 locally and your deployment pipeline watches for tags on the remote.

Question: What important step from the lesson must you remember?

Identify the extra action needed because tags are not pushed automatically with branch pushes.

Scenario: You checked out v1.0.0 to investigate an older release and now need to make a hotfix based on that state.

Question: What is the safest next step from the tutorial?

Choose the action that avoids staying in detached HEAD when continuing work from a tag.