Basic

Tagging a release in git

A release is a commit, and a commit hash is hard to find. A tag names it, and the tag is what a build, a bug report, and a bisect all point at. Untagged releases are a history you cannot navigate.

What you will see

The releases in date order - the answer to 'what shipped in March'.

About 1 min of reading

Try It

Tag a release.

1

The tag

git tag -a v2.4.1 -m 'Fix upload timeout; no API changes'

Before you run it, say out loud what it will print. Then open the answer.

What it prints
An annotated tag with the note about what shipped, which is the thing a later reader needs.
2

The list

git for-each-ref --sort=-committerdate refs/tags --format='%(refname:short) %(committerdate:short)'

Before you run it, say out loud what it will print. Then open the answer.

What it prints
The releases in date order - the answer to 'what shipped in March'.

Data Flow

A commit becomes a name.
1 Build the artifact
↓
2 Annotate the commit
↓
3 Push the tag
↓
4 Reference it later
Why this works
Push the tags

Tags do not travel with a branch by default. A release tag that never reached the remote is a release no one else can build from, which is the failure mode of a local only workflow.

List them

A command that lists the tags with their dates is the release history. That list is what a team reads when asked 'what shipped in March', and it only works if the tags exist.

Examples

Annotated, not lightweight

An annotated tag is an object with a date, an author, and a message. A lightweight tag is a pointer. For a release, the object is what you want, because the message is where the 'what shipped' note lives.

Tag the build, not the merge

Tag the commit that is the artifact. Tagging a merge that happened later tags something that was not shipped, and the difference matters when you rebuild from the tag.

One naming rule

v2.4.1 or release-2.4.1, chosen once and used always. Two conventions in one repository is a search that misses half the releases.

Words this lesson uses

Each one is defined here on this site. Open the entry for the full definition and the other words it points at.

← Semantic version numbers
Previous Lesson
Semantic version numbers
Next Lesson
Writing a changelog
Writing a changelog →