Managing Git Tags
Table of contents
1 - What is a tag?
A tag is a permanent pointer to a specific commit.
Difference between tag and branch
| Aspect | Tag | Branch |
|---|---|---|
| Movable | ❌ No | ✅ Yes |
| Usage | Mark a version | Development |
| Example | v1.0.0, release-2024 | main, feature/x |
Visualization
v1.0.0 v1.1.0 v2.0.0
↓ ↓ ↓
A───B───C───D───E───F───G───H───I───J───K main
Tags stay fixed on their commits, even as the branch moves forward.
🔝 Back to table of contents
2 - Types of tags
Lightweight tags
A simple pointer to a commit.
git tag v1.0.0
Annotated tags (recommended)
Contain metadata: author, date, message.
git tag -a v1.0.0 -m "Version 1.0.0 - Release initiale"
Comparison
| Aspect | Lightweight | Annotated |
|---|---|---|
| Metadata | ❌ | ✅ |
| Message | ❌ | ✅ |
| Signable (GPG) | ❌ | ✅ |
| Recommended use | Temporary | Production |
💡 Recommendation: Always use annotated tags for releases.
🔝 Back to table of contents
3 - Creating tags
Annotated tag on HEAD
git tag -a v1.0.0 -m "Release version 1.0.0"
Tag on a specific commit
git tag -a v1.0.0 abc1234 -m "Release version 1.0.0"
Signed tag (GPG)
git tag -s v1.0.0 -m "Signed release"
Verify a signed tag
git tag -v v1.0.0
View the details of a tag
git show v1.0.0
🔝 Back to table of contents
4 - Managing tags
List the tags
# Tous les tags
git tag
# Avec un pattern
git tag -l "v1.*"
# Triés par version
git tag -l --sort=-version:refname
Delete a tag
# Localement
git tag -d v1.0.0
# Sur le remote
git push origin --delete v1.0.0
# ou
git push origin :refs/tags/v1.0.0
Rename a tag
# Créer le nouveau
git tag new-tag old-tag
# Supprimer l'ancien
git tag -d old-tag
git push origin :refs/tags/old-tag
# Pousser le nouveau
git push origin new-tag
Check out a tag
# Aller sur le tag (detached HEAD)
git checkout v1.0.0
# Créer une branche depuis un tag
git checkout -b hotfix/v1.0.1 v1.0.0
🔝 Back to table of contents
5 - Tags and GitHub
Push the tags
# Un tag spécifique
git push origin v1.0.0
# Tous les tags
git push origin --tags
# Seulement les tags annotés
git push origin --follow-tags
Fetch the tags
git fetch --tags
GitHub Releases
On GitHub, tags are used to create Releases:
- Go to your repository → Releases
- Click Create a new release
- Select an existing tag or create a new one
- Add release notes
- Upload binaries if needed
Direct link to a tag
https://github.com/user/repo/releases/tag/v1.0.0
🔝 Back to table of contents
6 - Semantic versioning
SemVer format
MAJOR.MINOR.PATCH
│ │ │
│ │ └── Bug fixes (rétrocompatible)
│ └──────── Nouvelles fonctionnalités (rétrocompatible)
└─────────────── Changements incompatibles
Examples
| Version | Meaning |
|---|---|
1.0.0 | First stable release |
1.1.0 | New feature |
1.1.1 | Bug fix |
2.0.0 | Breaking changes |
Pre-releases
1.0.0-alpha
1.0.0-beta.1
1.0.0-rc.1
1.0.0
Release workflow
# 1. Mettre à jour le numéro de version dans package.json
# 2. Commiter
git commit -am "chore: bump version to 1.2.0"
# 3. Créer le tag
git tag -a v1.2.0 -m "Release version 1.2.0
Features:
- New login page
- Improved performance
Bug fixes:
- Fixed button click issue"
# 4. Pousser
git push origin main --follow-tags
Command summary
| Command | Description |
|---|---|
git tag | List the tags |
git tag -a v1.0.0 -m "msg" | Create an annotated tag |
git show v1.0.0 | View the details |
git tag -d v1.0.0 | Delete locally |
git push origin v1.0.0 | Push a tag |
git push origin --tags | Push all tags |
git checkout v1.0.0 | Check out a tag |