Git Tag Inspection and Deletion

Intermediate

Learner goal

By the end of this lesson, you should be able to list tags, inspect a tag and its annotation, filter tags by their relationship to commits, and delete a tag reference while understanding exactly what that deletion changes.

List tags without changing repository state

Running `git tag` with no creation, deletion, or verification option lists tag names. `git tag -l` is the explicit listing form, and a pattern can restrict the names that are shown. Listing is observational: it does not move a tag, branch, or HEAD.

git tag
git tag -l

git tag -l "v2*"

git tag -l "v2*"?matching tag names are displayed

Inspect a tag and its annotation

`git show <tag>` resolves the tag and displays the object it names. For an annotated tag, the output includes the tag object information and then the tagged object. `git tag -n` provides a tag-listing view that includes annotation text. These are inspection operations; they do not create a new tag or alter the target.

git tag -n

git show release-2.0
git show temp-label

git show release-2.0?the tag information and the tagged object are displayed

Filter tags by the objects they relate to

The listing form can answer different relationship questions without manually resolving every tag. `--points-at <object>` lists tags whose references point directly at the specified object. `--contains <commit>` lists tags that contain the commit in their reachable history, while `--no-contains <commit>` selects tags that do not. These filters answer different questions: direct reference target versus commit ancestry.

git tag --points-at HEAD
git tag --contains HEAD~1
git tag --no-contains HEAD~1

git tag --points-at HEAD?tags directly pointing at HEAD

Use merged and unmerged filters for release-oriented inspection

`--merged <commit>` lists tags whose tagged commits are reachable from the specified commit; `--no-merged <commit>` lists tags whose tagged commits are not reachable from it. This makes the filters useful for answering whether tagged history has already been incorporated into a chosen line of development. Do not silently treat `--merged` as a direct-target test: ancestry is the question here.

git tag --merged HEAD
git tag --no-merged HEAD

git tag --merged main?tags whose tagged commits are reachable from main

Delete the tag reference deliberately

`git tag -d <tagname>` deletes the named tag reference. It does not rewrite the tagged commit, and it does not mean “delete the commit.” For an annotated tag, the tag reference is what made the tag object reachable by that name; after deletion, the reference is gone. Git's documentation does not define `git tag -d` as an immediate object-garbage-collection operation, so this lesson verifies the reference transition rather than claiming that the underlying object is instantly destroyed.

git show-ref --tags
git tag -d temp-label
git show-ref --tags

git tag -d temp-label?refs/tags/temp-label is removed

Deletion can be verified by reference and object observations

A reliable deletion test checks the reference itself rather than trusting only the command's printed message. Before deletion, `git rev-parse refs/tags/<name>` resolves the tag reference. After deletion, that exact ref must no longer resolve. If you saved the object ID beforehand, an immediate `git cat-file -t <object-id>` check can also show that deleting the ref is not the same operation as deleting the underlying object from the object database. The latter observation is about the current repository state; it is not a promise that an unreachable object will remain forever.

tag_oid=$(git rev-parse refs/tags/temp-label)
git tag -d temp-label

git rev-parse --verify refs/tags/temp-label
# expected: failure; the ref no longer exists

git cat-file -t "$tag_oid"
# the previously resolved object can still be inspected immediately

git rev-parse --verify refs/tags/temp-label?the deleted ref no longer resolves

Do not confuse deletion with replacement

This lesson deliberately separates deletion from creation and replacement. `git tag -f` replaces an existing tag when creating a tag with the same name; `git tag -d` removes the tag reference. V457 owns creation semantics, so use that lesson for lightweight versus annotated creation. The next lesson owns cryptographic tag verification, not ordinary listing or deletion.

Practice what you learned

Use the dedicated Git code-completion exercise for this lesson.

Official-source boundary

This lesson uses the official Git `git-tag` documentation as its primary authority, with the official Git revisions documentation only for the meaning of commit reachability used by the relationship filters. The live official documentation baseline is Git 2.56.0. The local verifier may run an older Git executable; observed verification is reported separately from the official documentation version.