Git Tags

Git Tags

Tags mark specific commits as significant — typically used for releases. Unlike branches, tags don’t move as new commits are added.

Tag Types

Type	Description
Lightweight	Just a name pointing to a commit — like a branch that doesn’t move
Annotated	Full object with tagger, date, message, and optionally a GPG signature

Use annotated tags for releases — they contain metadata and show up in git describe.

Creating Tags

# Annotated tag (recommended for releases)
git tag -a v1.2.0 -m "Release version 1.2.0"

# Annotated tag on a specific commit
git tag -a v1.1.5 abc1234 -m "Hotfix 1.1.5"

# Lightweight tag (no metadata)
git tag v1.2.0

Viewing Tags

# List all tags
git tag

# Filter by pattern
git tag -l "v1.*"

# Show tag details
git show v1.2.0

# Show only tag names (for scripting)
git tag -l

Pushing Tags

Tags are not pushed automatically:

# Push a specific tag
git push origin v1.2.0

# Push all tags
git push origin --tags

# Push annotated tags only (not lightweight)
git push origin --follow-tags

Deleting Tags

# Delete locally
git tag -d v1.2.0-rc1

# Delete from remote
git push origin --delete v1.2.0-rc1
git push origin :refs/tags/v1.2.0-rc1   # equivalent

Checking Out a Tag

Tags put you in “detached HEAD” state — you’re not on a branch:

git checkout v1.2.0
# HEAD is now at abc1234... Release version 1.2.0
# (detached HEAD state)

To work from a tag, create a branch:

git checkout -b hotfix/v1.2.1 v1.2.0

Semantic Versioning

The widely adopted MAJOR.MINOR.PATCH convention:

MAJOR — breaking changes
MINOR — new backwards-compatible features
PATCH — backwards-compatible bug fixes

Pre-release: v1.2.0-alpha.1, v1.2.0-beta.2, v1.2.0-rc.1
Build metadata: v1.2.0+build.20250124

# Current release
git tag -a v1.2.0 -m "Add OAuth support"

# Bug fix
git tag -a v1.2.1 -m "Fix session expiry bug"

# New feature (backwards compatible)
git tag -a v1.3.0 -m "Add dark mode"

# Breaking change
git tag -a v2.0.0 -m "Redesign API — remove deprecated endpoints"

git describe

Find the most recent tag reachable from a commit:

git describe
# v1.2.0-3-gabc1234
# = tag v1.2.0, 3 commits ahead, current commit is abc1234

Useful for generating version strings in CI/CD builds.

GitHub Releases

Tags integrate with GitHub Releases:

# Tag and push
git tag -a v1.2.0 -m "Release 1.2.0"
git push origin v1.2.0

Then on GitHub: go to the tag → “Create release” → add release notes and attach build artifacts.

Using GitHub CLI:

gh release create v1.2.0 --title "Version 1.2.0" --notes "Bug fixes and improvements"
gh release create v1.2.0 ./dist/my-app-linux-amd64 ./dist/my-app-windows-amd64.exe

Automating Tags in CI/CD

# GitHub Actions — tag and release on push to main
- name: Bump version and create tag
  uses: mathieudutour/github-tag-action@v6.1
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    default_bump: patch

Or trigger a build from a tag push:

on:
  push:
    tags:
      - 'v*'