task-manager is about to have its first stable version. The team wants to be able to say "this is 1.0.0" and, two years from now, when an issue arrives from a client still on that version, for anybody to be able to stand exactly on that code without having to remember a forty-character hash or rummage through git log by date.

That is what tags are for: permanent names pointing at one specific commit. Unlike a branch, which moves on every time you commit, a tag stays put. v1.0.0 means today, tomorrow and a decade from now exactly the same commit.

And there is a second thing to learn here: in lesson 01-04 we saw that Git's database stores four types of object — blob, tree, commit and tag — and about the fourth we said hardly anything. This lesson completes it. Because it turns out there are two very different kinds of tag, and the difference between them is exactly whether that tag object exists or not.

1. What a tag is and how it differs from a branch
2. Lightweight versus annotated tags
3. Creating tags
4. Listing, searching and examining tags
5. Tagging a commit from the past
6. Semantic versioning
7. Pushing tags to the remote
8. Deleting tags and why they do not move
9. Signed tags
10. git describe: naming any commit
11. Working on a tag

Remember lesson 03-01: a branch is a 41-byte file in .git/refs/heads/ containing a hash. A tag is the same thing, but in .git/refs/tags/:

The difference is not in the format but in the behaviour:

That "does not move on its own" is the whole value of the tool. If you stand on v1.0.0 three years from now, you see exactly what was there when it was released, even if main has taken a thousand commits since.

main carries on moving to the right; v1.0.0 and v1.0.1 stay nailed where they were put.

Here is the lesson's central concept.

A lightweight tag is exactly what you have just seen: a file with a hash in it. A bare pointer, nothing more. It creates no new object in the database.

An annotated tag creates a complete tag object in Git's database, with a hash of its own, containing: which commit it points at, who created it, when, a message, and optionally a cryptographic signature. And refs/tags/v1.0.0 points at that object, not at the commit.

Let us look at it with the tools of 01-04:

The reference resolves directly to a commit: there is no intermediate object.

There it is, the fourth type of object, at last in its natural habitat. Note the structure: object (what it points at), type (what the pointed-at thing is), tag (the name), tagger (who and when) and the message. And like every Git object, it is immutable: its hash is computed over that content.

The full comparison:

Why annotated tags are always used for releasing versions, in four concrete reasons:

1. They record who and when. A v1.0.0 with no author and no date does not answer "who decided this was 1.0?".
2. They carry a message. That message is the natural place for the release notes, and it travels with the repository.
3. They can be signed. A signed tag allows cryptographic verification that the version was released by whoever it claims.
4. Git treats them as first-class citizens. git describe prefers them, push --follow-tags only sends those, and several tools in the ecosystem expect them.

The practical rule is simple: lightweight tag = disposable personal marker; annotated tag = everything else.

When the editor opens, write a subject on the first line, a blank line and the body. It is exactly the convention of commit messages (lesson 08-01):

A warning about names: they are Git references, so the same rules as for branches apply (lesson 03-06). No spaces, no .., no ~, ^, :, ?, *, [, no @{, no ending in . or in .lock. The overwhelmingly dominant convention is v followed by the number: v1.0.0, v2.3.1.

And a precaution that avoids a classic problem: do not use the same name for a branch and a tag. If v1.0.0 exists both as a branch and as a tag, git checkout v1.0.0 is ambiguous, Git warns you and applies a precedence rule nobody remembers. We saw it in passing in 04-05 when discussing full refspecs; the solution is not to create the problem.

Sorted alphabetically, which is the wrong order for versions: v1.10.0 comes out before v1.2.0. Git knows this and has a solution:

v:refname sorts by understanding the semantics of version numbers, and the - reverses it to put the newest at the top. It is worth leaving configured:

Filtering by pattern with -l (or --list), which accepts shell wildcards:

Seeing each tag's information in the listing:

Examining a tag thoroughly with git show:

With an annotated tag you see two blocks: first the tag (with its tagger, its date and its message) and then the commit it points at with its diff. With a lightweight one you would see only the commit, because there is nothing else to see.

Other useful queries:

That last one is among the most useful in the repertoire: it answers "which version was this fixed in?" without opening anything.

Tags work like any other reference in ranges, diff, log and show. Everything you learned in lesson 02-06 applies here.

It is common to realise that something needs tagging after you have carried on working. You simply pass the commit:

One important detail is visible there: the tag's date is today's, not the commit's. That is correct: the tag was created today, even though it marks something from weeks ago. If for some reason you need them to match:

And since the commit can be given with any of the expressions you know (lesson 02-06), all of this is valid:

Tagging v1.0.0 means nothing if the team does not share an understanding of what that number says. Semantic versioning (SemVer) is the most widespread convention for giving it meaning.

Format: MAJOR.MINOR.PATCH

Applied to the real history of task-manager:

Two rules that are often overlooked:

• Version 0.x.y is territory with no guarantees. Before 1.0.0, the convention explicitly says that anything may change. It is where to be while the design has not settled.
• Once released, a version is never touched again. If v1.0.0 had a bug, you release v1.0.1. You never re-tag v1.0.0 (section 8).

SemVer also allows suffixes for pre-releases and build metadata:

In SemVer's ordering, v2.0.0-alpha.1 < v2.0.0-rc.1 < v2.0.0: pre-release suffixes come before the final version. git tag --sort=-v:refname understands this correctly.

How it is decided what goes into each version, who approves it, how the notes are generated and how the release is automated are matters of team process and continuous integration: you will see them in modules 7 and 10. Here we are concerned with the Git mechanism.

In lesson 04-05 we left this open with a sentence that surprises everyone: git push does not send tags. Now we close the subject.

The reason is the default refspec (lesson 04-02): refs/heads/*:refs/heads/*. It only covers branches. refs/tags/* falls outside it.

The tag has been created locally and there it stays. The three ways of sending it:

--tags has a real problem: it also sends todays-tests, before-the-rebase and any lightweight marker you happen to have lying around, and once on the server they belong to everyone. That is why --follow-tags is almost always the right option, and why it is worth leaving configured:

From then on, an ordinary git push takes the relevant annotated tags with it and no others.

A nuance about --follow-tags: it only sends annotated tags and only those pointing at commits that are already, or are about to be, on the server. It is exactly what you want, and it is another practical reason for always using annotated tags when releasing versions.

On the receiving side there is nothing special to do: git fetch and git pull bring the tags of the commits they download. If you need to fetch them all explicitly:

Deleting locally:

Deleting on the remote (the same branch-deletion syntax from 04-05):

And now the important part: why is moving an already published tag a bad idea?

Technically you can. git tag -f v1.0.0 <another-commit> re-points it, and git push --force origin v1.0.0 re-points it on the server. But:

1. Nobody finds out. Whoever already had v1.0.0 downloaded does not get it updated by an ordinary git fetch. Git is deliberately conservative with existing tags: if the name already exists locally, it does not touch it. Result: for months, your v1.0.0 and Bruno's point at different commits, and neither of you knows.
2. It breaks the entire premise. A tag is worth something because it is stable. A tag that can change is useless: you can no longer cite it in an issue, in a deployment or in a document.
3. Artefacts already released do not change. If v1.0.0 is deployed at a client, moving the tag does not move the client's code. All it achieves is a tag that lies about what was deployed.
4. It is the same violation of the module's golden rule. Rewriting something others have already downloaded is not a local operation.

Whoever receives a moved tag sees this, if they force it:

And from there on they may struggle to work out which one was the right one.

What to do instead:

In short: a tag is a commitment. Once sent to the server, it is treated as immutable.

An annotated tag can carry a cryptographic signature proving who created it:

What it is for in practice: if somebody distributes task-manager by downloading the v1.0.0 tag from the server, the signature lets them check that the version really was released by Ana and not by somebody who got access to the server.

It only works with annotated tags — a lightweight one has nowhere to store the signature — and it requires a key to be configured (user.signingkey, gpg.format, tag.gpgSign). The full configuration, including signing with SSH keys and signing commits, is in lesson 08-05: Security Best Practices. Here it is enough to know that the option exists and that it is one more reason to use annotated tags.

You have some commit or other, in the middle of development, and you want a readable name for it. git describe builds one from the most recent tag that reaches it:

It reads like this:

If you are exactly on a tag, the name is the tag on its own:

Important options:

The combination used in practice for versioning builds:

That identifier is extraordinarily useful: it is embedded in the application and, when somebody reports a bug from an intermediate version, you know exactly which commit they are talking about and whether it came from a dirty working tree. For example, in task-manager:

And --contains, for the inverse question:

"That commit is two commits before v1.0.1", that is: it went into version 1.0.1.

Standing on a tag leaves you in detached HEAD (lesson 03-02), because a tag is not a branch and cannot advance:

That is fine for looking: inspecting that version's code, running it, reproducing a bug. But if you are going to work — for example, to fix a bug in 1.0 in order to release a 1.0.1 — you need a branch:

Now we are talking: a maintenance branch starting exactly at the released version. You fix it (or bring the fix over from main with git cherry-pick -x, lesson 05-03), commit, tag the new version and push it:

That is the complete cycle of a maintenance release, and it uses four things from this module at once.

You can also export a tag's content without cloning anything:

git archive generates a .zip (or .tar.gz) with that tag's tree, without the .git directory. It is the canonical way of producing a release package.

Mistake 1: creating lightweight tags for versions. git tag v1.0.0 without -a records neither who, nor when, nor why, cannot be signed and is not sent by --follow-tags. For versions, always -a.

Mistake 2: believing git push sends tags. It does not. It is the classic surprise: you create v1.0.0, you push, and it is not on the server. git push origin v1.0.0 or push.followTags true.

Mistake 3: using --tags out of habit. It sends all your local tags, test markers included. Once on the server, cleaning them up is awkward and everyone has to be told.

Mistake 4: moving a published tag. Whoever already had it does not get it updated and you end up with two different truths. If there is a bug, you release the next version.

Mistake 5: trusting alphabetical order. v1.10.0 comes before v1.2.0 alphabetically. Configure tag.sort -v:refname.

Mistake 6: using the same name for a branch and a tag. It creates ambiguities in checkout, switch and push that are hard to understand afterwards.

Mistake 7: expecting git describe to see lightweight tags. By default it only looks at annotated ones. If your repository has only lightweight tags, git describe fails with no names found; there you need --tags.

Tip 1: tag from main and only what gets released. One tag per real version. Tagging intermediate commits "just in case" fills the namespace with permanent noise.

Tip 2: write a real message. The tag message is the best place for the release notes: it travels with the repository, does not depend on any external tool and is read with git show.

Tip 3: embed git describe --tags --always --dirty in your builds. It is the cheapest way of ensuring that every bug report includes the exact version.

Tip 4: git tag --contains <sha> to answer "which version did this go into?". It is quicker and more reliable than searching the log by date.

Tip 5: agree SemVer with the team and write it down. The value of MAJOR.MINOR.PATCH lies in everyone understanding the same thing. A version number nobody knows how to interpret is just a number.

In a practice repository with at least three commits:

1. Create a lightweight tag and an annotated one on the same commit.
2. Demonstrate with git cat-file -t that one resolves to commit and the other to tag.
3. Show the content of the tag object with git cat-file -p and identify its five parts.
4. Compare the output of git show on each.

Simulate the evolution of task-manager:

1. Three commits and v1.0.0 (annotated, with a release-notes message).
2. A fix commit and v1.0.1.
3. Two new-functionality commits and v1.1.0.
4. List the tags sorted by version, newest to oldest.
5. Show what changed between v1.0.0 and v1.1.0.
6. Work out which version the fix commit went into without looking at the log.

Starting from exercise 2:

1. Add four more commits to main and check the output of git describe. Interpret each part.
2. Modify a file without committing and observe the effect of --dirty.
3. Create a maintenance branch starting at v1.0.0.
4. Take the 1.0.1 fix over to that branch with a cherry-pick, and tag the result as v1.0.2.
5. Check with git describe on each branch that the names are coherent.

Solution 1:

The five parts: object (the commit pointed at), type (what it is), tag (the name), tagger (authorship and date) and the message.

The annotated one shows one extra block: its own.

Solution 2:

It went into v1.0.1 (the first in the list) and, naturally, it is still present in v1.1.0.

Solution 3:

The most recent reachable annotated tag is v1.1.0, 4 commits have gone by since it, and the current commit is 9e2c6b1.

Each branch is named with respect to its own line of tags, which is exactly what you expect from a versioning scheme with maintenance branches.

Tags are the repository's stable memory. The essentials:

• A tag is a reference that does not move. It lives in refs/tags/, marks one specific commit for ever and cannot be the destination of HEAD (it leaves you in detached HEAD).
• There are two kinds. The lightweight one is a bare pointer, with no object of its own. The annotated one creates a tag object in the database — the fourth type from lesson 01-04 — with author, date, message and optional signature. For released versions, always annotated.
• They are created with git tag -a <name> -m "...", optionally on a commit from the past; they are listed with git tag -l "<pattern>", -n and --sort=-v:refname; they are examined with git show; and git tag --contains <sha> answers "which version did this go into?".
• Semantic versioning (MAJOR.MINOR.PATCH) gives the number a shared meaning: incompatible / new functionality / fix. Before 1.0.0 there is no commitment; afterwards, a released version is never touched.
• Tags do not travel on their own: git push origin <tag> for a specific one, --tags for all of them (rarely what you want) and --follow-tags — or push.followTags true — for the reachable annotated ones, which is the right thing day to day.
• They are deleted with git tag -d locally and git push origin --delete on the remote, but a published tag does not move: whoever already has it does not get it updated, and the result is two different truths coexisting. If there is a bug, you release the next version.
• git describe --tags --always --dirty names any commit with respect to the last tag and is the canonical way of versioning builds.
• To work on a released version, create a branch from the tag; the tag on its own is only good for looking.

We now know how to mark the past. What is missing is the complementary operation, and the most delicate of them all: undoing it.

Because it is going to happen. Somebody is going to publish a commit on main that breaks something, and it will already be on the server, and three people will have it downloaded. The golden rule forbids rewriting it. So what then?

Git has an answer for that, and it is an elegant one: not deleting the commit, but adding another one that applies the opposite change. That is git revert, the only safe way of undoing something that is already public, and with it we close the module in lesson 05-06: Reverting Commits.