Arc 3 Quest 13

The Magic Seals

Tags and semantic versioning

The Master Archivist leads you into the Hall of Seals, a circular chamber whose walls are covered with ancient scrolls. Each one bears a wax seal at a specific spot - some golden, others scarlet. You notice that these seals are not placed randomly: they mark the most important moments in the kingdom's History.

"Archivist, you now know how to set aside your work, track down bugs through History, and pluck commits from one branch to another. But you are missing an essential art: placing Magic Seals on the key moments of your chronicles. A seal is a permanent mark, a bookmark placed on a precise instant so it can be found forever. The founding of a guild, a great victory, the rebuilding after a siege - every major event deserves its seal."

What is a tag?

A tag in Git is like a wax seal placed on an important scroll. Unlike branches that move with each new commit, a tag is fixed - it always points to the same commit.

Tags are used to mark important moments in a project's history:

  • The release of a stable version (v1.0.0, v2.0.0)
  • An important project milestone (MVP, beta)
  • A reference point to easily return to a known state

A branch is a living path that grows with every step. A seal, however, is carved in stone. It doesn't move. It says: here, something important happened.

Lightweight tags vs annotated tags

Git offers two types of tags, like two types of seals.

Lightweight tag (lightweight)

A lightweight tag is simply a pointer to a commit. No extra metadata - just a name associated with a commit.

git tag v0.1.0

It's like writing a number in pencil in the margin of a scroll. It's quick, but there's no additional information.

Annotated tag (annotated)

An annotated tag contains much more information:

  • The tag name
  • The date of creation
  • The author's name
  • An explanatory message
git tag -a v1.0.0 -m "First stable version of the kingdom"

It's a proper official wax seal: it bears the Archivist's mark, the date, and a description of why this moment is important.

"Lightweight Seals are useful for personal, temporary use. But for everything that matters - official releases, shared milestones - always use an Annotated Seal. It's the difference between a scribbled note and a royal decree."

Recommendation: In practice, always use annotated tags for versions and milestones. Lightweight tags are reserved for temporary bookmarks.

Creating a tag

Lightweight tag

# Tag the current commit (HEAD)
git tag v0.1.0

Annotated tag (recommended)

# Tag the current commit with a message
git tag -a v1.0.0 -m "First stable version"

The -a option means "annotated" and -m lets you add a message, exactly like git commit -m.

Tagging a past commit

You can also place a seal on an old commit. Just specify the commit hash:

# Find the hash of the commit to tag
git log --oneline

# Tag that commit
git tag -a v0.1.0 abc1234 -m "Founding of the guild"

It's like going back through the archives to stamp a seal on a past event that no one had thought to mark at the time.

Exploring tags

List all tags

git tag

Displays the list of all tags, sorted alphabetically.

Filter tags by pattern

# All tags starting with "v1."
git tag -l "v1.*"

# All tags starting with "v"
git tag -l "v*"

The -l (list) option accepts a pattern with wildcard characters (*).

View tag details

git show v1.0.0

For an annotated tag, git show displays:

  • The tag author and date
  • The tag message
  • The associated commit details (author, date, message, diff)

For a lightweight tag, git show only displays the commit details (no additional tag information).

"That is how you tell a true Seal from a simple pencil mark. The Annotated Seal bears the signature of its creator and the reason it was placed."

Sharing tags

By default, git push does not push tags. You must send them explicitly.

Push a specific tag

git push origin v1.0.0

Push all tags

git push origin --tags

--tags pushes all local tags. If you have temporary tags you don't want to share, push them one by one.

Deleting a tag

Delete a local tag

git tag -d v0.1.0

The tag is deleted locally. If you had already pushed it to a remote repository, you must also delete it there:

git push origin --delete v0.1.0

"One only breaks a Seal with good reason. A Seal placed by mistake can be removed, but a Seal shared with other guilds requires more work to erase."

Semantic versioning

Tags often follow a convention called Semantic Versioning (SemVer). The format is:

vMAJOR.MINOR.PATCH
Part When to increment Example
MAJOR Incompatible change (breaking change) v1.0.0 to v2.0.0
MINOR New backward-compatible feature v1.0.0 to v1.1.0
PATCH Backward-compatible bug fix v1.0.0 to v1.0.1

Concrete examples

  • v0.1.0 - first development version, not yet stable
  • v1.0.0 - first stable version, ready for production
  • v1.0.1 - bug fix in v1.0.0
  • v1.1.0 - new feature added to v1.0
  • v2.0.0 - major overhaul, not backward-compatible

"Semantic versioning is the common language of guilds. When an Archivist sees v2.0.0 go by, they know that major changes have occurred. When they see v1.0.1, they know it's a simple repair. The numbers speak for themselves."

When to place a seal?

Here are the moments when you should tag:

  • Release: every version delivered to users (v1.0.0, v1.1.0)
  • Milestone: every important project step (v0.1.0 for the MVP)
  • Stable version: a reliable reference point for other developers
  • Before a risky change: so you can easily roll back if something goes wrong

Don't tag everything. A tag should mark a significant moment. If you tag every commit, tags lose their value - like placing a seal on every page of a book.

Practical exercise - Seal the Kingdom's Chronicles

Create the kingdom's chronicles and mark the three most important moments in its history:

  1. Create a repository with a first commit and tag it v0.1.0 (lightweight tag)
  2. Add commits to develop the kingdom
  3. Mark the first great victory with an annotated tag v1.0.0
  4. Add repair commits after a siege
  5. Mark the repair with an annotated tag v1.0.1
  6. Explore and inspect your tags
  7. Run the verification script

Step 1 - Create the repository and the guild's founding

mkdir magic-seals
cd magic-seals
git init -b main

Create the first scroll and make the first commit:

echo "# Chronicles of the Kingdom" > chronicles.txt
echo "" >> chronicles.txt
echo "Year 1 - The Guild of Archivists is founded." >> chronicles.txt
git add chronicles.txt
git commit -m "Found the Guild of Archivists"

Place a lightweight tag on this founding moment:

git tag v0.1.0

Step 2 - Develop the kingdom

echo "Year 2 - The first apprentices join the guild." >> chronicles.txt
git add chronicles.txt
git commit -m "Welcome the first apprentices"

echo "Year 3 - The guild explores the Northern lands." >> chronicles.txt
git add chronicles.txt
git commit -m "Explore the Northern lands"

Step 3 - The first great victory

echo "Year 4 - The guild wins the Battle of Frostfort." >> chronicles.txt
git add chronicles.txt
git commit -m "Win the Battle of Frostfort"

Place an annotated tag to mark this major victory:

git tag -a v1.0.0 -m "First great victory - Battle of Frostfort"

Step 4 - Repair after the siege

echo "Year 5 - The siege of the Citadel causes heavy damage." >> chronicles.txt
git add chronicles.txt
git commit -m "Suffer the siege of the Citadel"

echo "Year 6 - The walls are rebuilt stronger." >> chronicles.txt
git add chronicles.txt
git commit -m "Rebuild the Citadel walls"

Place an annotated tag to mark the repair:

git tag -a v1.0.1 -m "Repair after the siege - Walls rebuilt"

Step 5 - Explore your seals

List all tags:

git tag

Filter version 1 tags:

git tag -l "v1.*"

Inspect an annotated tag:

git show v1.0.0

Compare with a lightweight tag:

git show v0.1.0

Notice the difference: the annotated tag shows the author, date, and tag message, while the lightweight tag directly shows the commit.

Step 6 - Run the verification

bash verifier.sh
.\verifier.ps1

Command summary

Command Description
git tag <name> Create a lightweight tag
git tag -a <name> -m "msg" Create an annotated tag (recommended)
git tag List all tags
git tag -l "v1.*" Filter tags by pattern
git show <tag> View tag details
git tag <name> <commit> Tag a past commit
git push origin <tag> Push a specific tag
git push origin --tags Push all tags
git tag -d <name> Delete a local tag

The Master Archivist contemplates the seals you have placed on the chronicles. He nods with satisfaction.

"You now master the art of Magic Seals. You know how to mark the important moments of History, distinguish a quick seal from an official seal, and find any milestone in an instant. This is a power that the best Archivists use with discernment - each seal must have a reason to exist."

He points to a final golden tag, hanging on the wall above the exit door.

"Remember: a good seal tells a story all by itself. Its name, its message, its placement - everything must be chosen with care. The Archivists who come after you will be grateful."