Git Basics: Marking a Version with an Annotated Tag

A tag gives a particular commit a memorable name. An annotated tag also stores a message and tagger information, making it useful for a version you want to identify later.

Run these commands in Bash with Git 2.28 or newer installed. Start a fresh temporary repository for this article:

git_practice=$(mktemp -d) || exit
cd "$git_practice" || exit
git init -q -b main
git config user.name 'Practice User'
git config user.email 'practice@example.invalid'
git config commit.gpgsign false

The identity and signing settings apply only to this repository. Use your own identity in real projects. The temporary files remain afterward. Examples assume default Git settings; if a pager opens, press q to leave it.

Name the first version

printf 'port=8080\n' > app.conf
git add app.conf
git commit -q -m 'Add application config'
git tag -a v0.1.0 -m 'First practice version'
git tag --list

v0.1.0

Without an explicit target, git tag uses the current commit. -a creates an annotated tag and -m supplies its message without opening an editor. This exercise uses Git’s default unsigned-tag behavior.

Read the annotation and snapshot

git for-each-ref --format='%(contents:subject)' refs/tags/v0.1.0
git show v0.1.0:app.conf

First practice version
port=8080

The first command prints the annotation’s subject. The second reads one file from the tagged snapshot without changing your working tree. For a fuller view, git show v0.1.0 includes the tag, commit, and patch; IDs and timestamps will vary.

Make another commit

printf 'port=9090\n' > app.conf
git add app.conf
git commit -q -m 'Change application port'
cat app.conf
git show v0.1.0:app.conf

port=9090
port=8080

The current file has changed, but the tag still identifies the earlier snapshot. A branch advances as you commit; a tag normally stays at its chosen version. Avoid moving a tag that others already use, because the same name would then refer to different history.

A tag created here is local. In a real project, git push origin v0.1.0 sends that named tag to the configured remote. Check the destination and the team’s release process first: publishing a tag can trigger automation. Creating a tag alone does not create a GitHub Release.

References

Git tag manual, Git show manual, and Git for-each-ref manual

Acknowledgements

This post was created with assistance from AI.