Git Tagging

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.

Lightweight Tag

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

git tag v1.0.0

This is quick and useful for personal or temporary markers.

Annotated Tag

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

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

Annotated tags are generally better for official releases.

Listing Tags

To list all tags:

git tag

To filter by a pattern:

git tag -l "v1.*"

This is useful when a repository has many releases.

Tagging Older Commits

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

git log --oneline

Then tag that specific commit:

git tag -a v0.9.0 a1b2c3d -m "Backfill tag for pre-release"

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

Pushing Tags to a Remote

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

Push one tag:

git push origin v1.0.0

Push all tags:

git push origin --tags

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

Deleting Tags

Delete a local tag:

git tag -d v1.0.0

Delete a remote tag:

git push origin --delete v1.0.0

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

Checking Out a Tag

You can inspect the repository at a tagged release:

git checkout v1.0.0

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:

git switch -c hotfix-from-v1.0.0

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

Release Example

A simple release workflow could look like this:

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

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

When to Use Each Tag Type

Use lightweight tags when:

• you need a quick local marker
• the tag is informal or temporary

Use annotated tags when:

• the tag represents a real release
• you want metadata and a message
• the tag will be shared with the team

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

Let's see how well you understood the concepts! These exercises will help reinforce what you just learned.

Exercise 1: Picking the right release marker

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?

Exercise 2: Publishing the release tag

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?

Exercise 3: Working from a tag

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?