Git Tags

Mark releases with tags, distinguish lightweight pointers from annotated records, and treat published version tags as immutable.

A tag gives one object a durable name

A branch ref normally moves as commits are added. A tag ref is intended to remain fixed. Teams use tags to identify releases, milestones, deployment inputs, or audited states. git tag is a Git command. GitHub Releases are a later hosting feature that typically points at a Git tag—they are not the same thing.

Annotated tags are usually the stronger release record because the metadata explains who created the label and what it represents. Cryptographically signed tags add verification when the project has a managed signing policy.

If you just transferred a fix with Git Cherry-Pick, tag the verified destination commit—not whichever commit happens to be HEAD.

Create an annotated tag at a verified commit

git status
git show --no-patch --format=fuller <release-commit>

# Create an annotated tag at the verified commit
git tag -a v1.4.0 <release-commit> -m "Release v1.4.0"

git show v1.4.0
git rev-parse v1.4.0^{}

Pass the commit explicitly instead of assuming HEAD. The peel expression v1.4.0^{} resolves the annotated tag to its target object, normally the commit used to build the release.

List, inspect, and relate tags to history

git tag --list 'v1.*' --sort=-version:refname
git for-each-ref refs/tags --format='%(refname:short) %(objecttype) %(taggerdate:iso8601) %(subject)'
git show v1.4.0
git tag --contains <commit>
git describe --tags --always <commit>

git describe names a commit relative to a reachable tag; it does not create or move a tag. Exact output depends on reachable tags and options, so use full commit IDs for security-sensitive identity.

Publish tags explicitly

# Push one reviewed release tag
git push origin v1.4.0

# Fetch remote tags
git fetch --tags

# Push a branch plus missing reachable annotated tags
git push --follow-tags origin main

# Inspect the remote tag ref
git ls-remote --tags origin refs/tags/v1.4.0 refs/tags/v1.4.0^{}

A normal branch push does not imply “publish every local tag.” --follow-tags pushes missing annotated tags reachable from refs being pushed; it does not mean all tags, and it does not replace deliberate release publication. Pushing a tag talks to a Git remote. That remote might be GitHub, GitLab, or another host.

Treat published version tags as immutable

If a release tag points to the wrong commit, stop distribution and follow an explicit incident policy. Often the safest public correction is a new version tag plus clear release notes.

# Local deletion
git tag -d v1.4.0

# Remote deletion — destructive and coordination-sensitive
git push origin :refs/tags/v1.4.0

Guided practice: tag a verified commit

1. 01
   Choose an explicit commit

   In a disposable repository, identify the tested commit you intend to name. Do not assume HEAD.

2. 02
   Create an annotated tag

   Use git tag -a with a version and a message that states what the name represents.

3. 03
   Peel and compare

   Show the tag object, peel it to the commit, and confirm the tree matches the tested snapshot.

4. 04
   Push one tag

   Publish that exact ref, then inspect the remote direct and peeled names.

5. 05
   Refuse a silent move

   Demonstrate locally that moving the tag changes its target, then delete the experiment without publishing the moved name.

Independent lab: audited release identity

1. Create a disposable repository with at least two commits and identify the one that represents a release.
2. Create v1.3.1 as an annotated tag on that explicit commit.
3. Inspect the tag object and the peeled commit. Record both object IDs.
4. If you have a disposable remote, push only that tag and inspect it from a second clone.
5. Move the tag locally, prove the target changed, then delete the local experiment without publishing the moved name.

Common tag mistakes

Lesson review

You can distinguish tag refs from tag objects, point an annotated version name at a verified commit, and treat published tags as immutable identities. GitHub Releases, when taught later, sit on top of this Git record.

• I can create, peel, inspect, push, and remotely verify an annotated tag.
• I pass an explicit commit instead of assuming HEAD.
• I treat published version tags as immutable release identities.
• I know git tag is Git, while GitHub Releases are a hosting feature.