Introduction to Git Tags

Ever needed to jump straight back to the exact commit you shipped as v1.0? That’s what Git tags are for. They’re named references that mark specific points in your repository’s history — release points, mostly, though I use them for anything worth bookmarking. Once you know how to create, push, and check out tags, you can navigate your codebase’s history without digging through git log. Here’s how I use them.

Listing Git Tags with git tag

Run git tag to see every tag in the repository:

git tag

v1
newsletter
rss
v2

Want to filter by pattern instead? The git tag documentation confirms -l accepts a shell wildcard, so git tag -l "v*" lists only tags starting with “v”.

git tag -l "v*"

v1
v2

Creating Annotated Tags with git tag -a

Annotated tags store extra information on top of just pointing at a commit — the tagger’s name, a date, and a message. Lightweight tags skip all that; they’re just a named pointer, much like a branch that never moves. The Git Basics - Tagging guide recommends annotated tags for anything you plan to release, since that metadata matters once you’re looking back through history. Creating one is simple: pass -a, a tag name, and a message:

git tag -a v1 -m "version 1"

This creates an annotated tag named v1 with the message “version 1”. Check the details with git show:

git show v1

You’ll get the tag message plus the commit it points to:

tag v1
Tagger: Elena  <my_email@gmail.com>
Date:   Sun Jun 18 15:09:31 2023 +0200

version 1

commit d77ebd3a1c62fcd2c12c743cf13751b317d8328b (tag: v1)
Author: Elena  <my_email@gmail.com>
Date:   Sun Jun 18 14:47:00 2023 +0200

Pushing Git Tags to a Remote Repository

Git doesn’t push tags along with your commits automatically — you have to do it explicitly. The git push documentation is clear on this: tags aren’t included by default. Push a single tag like this:

git push origin v1

Or push every local tag at once with --tags:

git push origin --tags

Checking Out a Tag and the Detached HEAD State

Sometimes you just want to look at the code as it was at a specific tag. Running git checkout with a tag name does that:

git checkout v1

This puts you in what the git checkout documentation calls a “detached HEAD” state: you’re no longer on a branch, and any commits you make there won’t belong to one.

Resolving commits made in a detached HEAD state requires a few steps to bring them into a branch. Here’s a guide to resolving commits in detached branch mode:

Identify the detached commit

Use the git log command to locate the commit hash or any identifiable information about the commit you made in the detached HEAD state. Refer to the Git Basics - Viewing the Commit History for different variations of the “git log” command.

Creating a Branch from a Tag

🔒 Subscribe to keep reading.

Final Thoughts

🔒 Subscribe to keep reading.

References

🔒 Subscribe to keep reading.