|$ curl https://forge-ai.dev/api/markdown?path=docs/git/tags

$cat docs/git-—-tags-&-releases.md

updated Recently·10 min read·published

Git — Tags & Releases

◆Git◆Beginner

Introduction

Tags in Git are static references to a specific commit, typically used to mark release points (v1.0, v2.3.1, etc.). Unlike branches, tags do not move when new commits are made — they are permanent markers in your project's history.

This guide covers lightweight and annotated tags, signing tags with GPG, semantic versioning conventions, and release tagging workflows.

Lightweight vs Annotated Tags

Git supports two types of tags: lightweight and annotated. The difference is that annotated tags store metadata (tagger name, email, date, message) and can be cryptographically signed.

Feature	Lightweight	Annotated
Storage	Just a name pointing to a commit	Full Git object with metadata
Tagger info	No tagger information	Stores name, email, date
Message	No message	Has a tag message (like a commit)
Signing	Cannot be signed	Can be GPG or SSH signed
Use case	Personal bookmarks, temporary markers	Releases, public tags

terminal

Bash

1	# Create a lightweight tag (just a pointer)
2	git tag v1.0.0
3
4	# Create an annotated tag (recommended for releases)
5	git tag -a v1.0.0 -m "Release v1.0.0 — stable API"
6
7	# Create an annotated tag with a longer message
8	git tag -a v1.0.0 -m "Release v1.0.0
9
10	This release introduces the new payment API
11	and deprecates the legacy checkout system."

✓

best practice

Always use annotated tags (git tag -a) for public releases. They provide provenance — anyone inspecting the tag can see who created it, when, and why. Use lightweight tags only for local, temporary markers.

Creating Tags

Tags can target the current commit, a specific commit hash, or even a previous tag. You can also tag after the fact — perfect for marking a commit you forgot to tag at release time.

terminal

Bash

1	# Tag the current commit
2	git tag -a v2.0.0 -m "Release v2.0.0"
3
4	# Tag a specific commit by hash
5	git tag -a v1.9.0 abc123def -m "Hotfix v1.9.0"
6
7	# Tag a commit relative to HEAD
8	git tag -a v1.8.0 HEAD~3 -m "Release v1.8.0"
9
10	# Tag the commit that created a specific branch
11	git tag -a v1.7.0 origin/main -m "Release v1.7.0"
12
13	# Create a tag with a message from a file
14	git tag -a v2.1.0 -F release-notes.txt
15
16	# Re-tag (move a tag to a different commit)
17	git tag -a -f v2.0.0 new-commit-hash -m "Moved tag"

⚠

warning

Moving a tag with -f is dangerous if the tag has already been pushed and others may have fetched it. Git tags are meant to be immutable. Only force-replace tags on unreleased commits or after coordinating with your team.

Viewing & Listing Tags

Git provides several ways to list, search, and inspect tags. Tags are sorted alphabetically by default, which aligns well with semantic versioning when using leading zeros.

terminal

Bash

1	# List all tags
2	git tag
3	# v1.0.0
4	# v1.1.0
5	# v2.0.0
6
7	# List tags matching a pattern
8	git tag -l "v2.*"
9	# v2.0.0
10	# v2.0.1
11
12	# Show tag details (annotated tag)
13	git show v1.0.0
14	# tag v1.0.0
15	# Tagger: Alice <alice@example.com>
16	# Date: Mon Mar 4 10:00:00 2024 +0000
17	# Release v1.0.0
18	# commit abc123def456...
19
20	# List tags with commit information
21	git tag -n
22	# v1.0.0 Release v1.0.0
23	# v1.1.0 Release v1.1.0 — minor features
24
25	# Sort tags by version (git 2.0+)
26	git tag --sort=-version:refname

Pushing Tags to Remote

Unlike branches, tags are not pushed automatically when you run git push. You must explicitly push tags to the remote repository.

terminal

Bash

1	# Push a specific tag
2	git push origin v1.0.0
3
4	# Push all tags that don't exist on remote
5	git push origin --tags
6
7	# Push tags matching a pattern
8	git push origin --follow-tags
9	# Only pushes annotated tags that are reachable from pushed commits
10
11	# Delete a tag on the remote
12	git push origin --delete v1.0.0
13
14	# Or use the refspec syntax
15	git push origin :refs/tags/v1.0.0
16
17	# Fetch tags from remote
18	git fetch --tags
19
20	# Fetch tags and prune deleted ones
21	git fetch --tags --prune

ℹ

info

Configure git config --global push.followTags true to automatically push annotated tags when you push commits they point to. This ensures you never forget to push a release tag after pushing release commits.

Deleting Tags

Deleting tags locally and on remote follows similar syntax. You should delete locally first, then push the deletion to the remote.

terminal

Bash

1	# Delete a local tag
2	git tag -d v1.0.0
3
4	# Delete a remote tag
5	git push origin --delete v1.0.0
6
7	# Delete multiple local tags
8	git tag -d v1.0.0 v1.1.0 v1.2.0
9
10	# Delete all local tags that match a pattern
11	git tag -d $(git tag -l "v1.0.*")
12
13	# Clean up remote tags that no longer exist locally
14	git fetch --tags --prune

Signed Tags (GPG)

Signed tags provide cryptographic verification that a tag was created by a trusted identity. This is important for open-source projects and software distribution, where consumers need to verify release authenticity.

terminal

Bash

1	# Create a GPG-signed tag
2	git tag -s v1.0.0 -m "Release v1.0.0"
3
4	# Create a tag signed with your default GPG key
5	# You'll be prompted for your GPG passphrase
6
7	# Verify a signed tag
8	git tag -v v1.0.0
9	# gpg: Signature made Mon Mar 4 10:00:00 2024
10	# gpg: using RSA key ABCDEF1234567890
11	# gpg: Good signature from "Alice <alice@example.com>"
12
13	# Configure Git to always sign tags
14	git config --global tag.gpgSign true
15
16	# List tags with verification status
17	git tag --verify
18
19	# If you don't have GPG, you can use SSH signatures:
20	git tag -s v1.0.0 -m "Release v1.0.0" # with ssh format
21	# Requires: git config gpg.format ssh

🔥

pro tip

Set up your GPG key in GitHub to display verified tags on your repository. Go to GitHub Settings > SSH and GPG keys to add your public key. Then tags you push with git tag -s will show as verified on the releases page.

Tags & Semantic Versioning

Git tags pair naturally with Semantic Versioning (SemVer). The standard convention is to prefix version numbers with v (e.g., v1.2.3), following the MAJOR.MINOR.PATCH format.

terminal

Bash

1	# Standard SemVer tag formats
2	git tag -a v1.0.0 -m "Initial stable release"
3	git tag -a v2.3.1 -m "Bugfix release"
4	git tag -a v3.0.0-alpha.1 -m "Alpha preview"
5	git tag -a v3.0.0-beta.2 -m "Beta release"
6	git tag -a v3.0.0-rc.1 -m "Release candidate"
7
8	# Pre-release suffixes sort before the release
9	# v3.0.0-alpha < v3.0.0-alpha.1 < v3.0.0-beta < v3.0.0-rc.1 < v3.0.0
10
11	# Build metadata (not used in precedence)
12	git tag -a v1.0.0+build.20240304 -m "With build metadata"
13
14	# Find the latest tag
15	git describe --tags --abbrev=0
16
17	# Find the latest tag matching a pattern
18	git describe --tags --match "v[0-9]*" --abbrev=0

ℹ

info

Use git describe --tags in your build scripts to embed the current version into your application. It returns the nearest tag with the number of commits since that tag and an abbreviated commit hash (e.g., v1.0.0-5-gabc1234).

Tagging Workflows for Releases

Teams adopt different tagging strategies depending on their release process. Here are common workflows for tagging releases:

terminal

Bash

1	# Workflow 1: Tag on main after merge
2	# 1. Feature branch merged to main
3	# 2. CI passes on main
4	# 3. Tag and release
5	git checkout main
6	git pull
7	git tag -a v1.2.0 -m "Release v1.2.0"
8	git push origin v1.2.0
9
10	# Workflow 2: Tag on release branch (Git Flow)
11	git checkout release/1.3
12	# ... final testing and fixes ...
13	git commit -m "Release 1.3 preparations"
14	git tag -a v1.3.0 -m "Release v1.3.0"
15	git push origin v1.3.0
16	git checkout main
17	git merge release/1.3
18
19	# Workflow 3: Automated tagging via CI
20	# In CI pipeline (GitHub Actions example):
21	# - name: Tag release
22	# run: \|
23	# git tag -a v${env.VERSION} -m "Release v${env.VERSION}"
24	# git push origin v${env.VERSION}
25	#
26	# This integrates with semantic-release for full automation

Best Practices

Always Use Annotated Tags for Releases

Public releases should always use annotated tags with a descriptive message. Lightweight tags are fine for personal bookmarks but lack the metadata needed for provenance.

Follow SemVer Conventions

Use the vMAJOR.MINOR.PATCH format for all release tags. This ensures compatibility with tools like npm version, Go modules, and semantic-release.

Automate Tagging in CI/CD

Use tools like semantic-release or CI pipeline scripts to create tags automatically. This reduces human error and ensures every release is properly tagged.

Sign Release Tags

For public packages and open-source projects, sign your release tags with GPG. This allows consumers to verify that the release was created by you and has not been tampered with.

$Blueprint — Engineering Documentation·Section ID: GIT-TAGS·Revision: 1.0

X GitHub YouTube Instagram Facebook Buy me a coffee Sponsor