06 - Tag

Comandi per creare marcatori permanenti di versioni specifiche del codice.

---

Cosa sono i Tag

I tag sono puntatori immutabili a commit specifici, usati principalmente per marcare versioni/release del software (v1.0.0, v2.1.3, ecc.).

Tipi di tag:

• Lightweight: semplice puntatore a commit
• Annotated: oggetto completo con autore, data, messaggio (raccomandato per release)

---

Creare Tag

Sintassi

git tag <nome-tag>                    # Lightweight
git tag -a <nome-tag> -m "messaggio"  # Annotated

Esempi pratici

Tag annotato (raccomandato):

git tag -a v1.0.0 -m "Release version 1.0.0"

Tag lightweight:

git tag v1.0.0-beta

Tag su commit specifico:

git tag -a v0.9.0 abc123 -m "Versione 0.9.0"

Tag con messaggio multi-riga:

git tag -a v2.0.0
# Si apre editor per messaggio dettagliato

Convenzioni naming tag

Semantic Versioning (raccomandato):

v1.0.0
v2.3.1
v0.1.0-beta
v1.0.0-rc1

Formato: vMAJOR.MINOR.PATCH

• MAJOR: breaking changes
• MINOR: nuove feature compatibili
• PATCH: bugfix

---

Listare Tag

Sintassi

git tag
git tag [opzioni]

Esempi pratici

Lista tutti i tag:

git tag

Output:

v0.1.0
v0.2.0
v1.0.0
v1.1.0

Lista tag con pattern:

git tag -l "v1.*"

Output:

v1.0.0
v1.1.0
v1.2.0

Tag con info commit:

git tag -n

Output:

v1.0.0    Release version 1.0.0
v1.1.0    Add new features

Tag con messaggi completi:

git tag -n5   # Primi 5 righe del messaggio

Info dettagliate tag annotato:

git show v1.0.0

Output:

tag v1.0.0
Tagger: Emanuele Gori <email@esempio.com>
Date:   Mon Dec 23 2024 10:00:00 +0100

Release version 1.0.0

Changelog:
- Feature A
- Feature B
- Fix bug C

commit abc123...

---

Eliminare Tag

Sintassi

git tag -d <nome-tag>              # Locale
git push origin --delete <tag>     # Remoto

Esempi pratici

Eliminare tag locale:

git tag -d v0.1.0-beta

Eliminare tag remoto:

git push origin --delete v0.1.0-beta
# oppure sintassi alternativa
git push origin :refs/tags/v0.1.0-beta

Eliminare tag locale e remoto:

git tag -d v1.0.0
git push origin --delete v1.0.0

---

Push Tag

Sintassi

git push origin <tag>       # Tag specifico
git push origin --tags      # Tutti i tag

Esempi pratici

Push tag specifico:

git tag -a v1.0.0 -m "Release 1.0.0"
git push origin v1.0.0

Push tutti i tag:

git push origin --tags

Push tag annotati (solo):

git push origin --follow-tags

Push solo tag annotati sui commit che stai pushando.

⚠️ Nota importante

I tag NON vengono pushati automaticamente con git push!

# Questo NON pusha i tag
git push origin main

# Devi pushare esplicitamente
git push origin v1.0.0

---

Checkout Tag

Sintassi

git checkout <tag>

Esempi pratici

Checkout di tag (detached HEAD):

git checkout v1.0.0

⚠️ Sei in "detached HEAD state". Commit fatti qui si perdono.

Creare branch da tag:

git checkout -b hotfix-v1.0 v1.0.0

Crea branch hotfix-v1.0 partendo dal tag.

Workflow hotfix da tag:

# 1. Checkout tag release
git checkout v1.0.0

# 2. Crea branch hotfix
git checkout -b hotfix-1.0.1

# 3. Fix bug
git add .
git commit -m "Fix critical bug"

# 4. Tag nuova versione
git tag -a v1.0.1 -m "Hotfix release 1.0.1"

# 5. Merge in main e push
git checkout main
git merge hotfix-1.0.1
git push origin main
git push origin v1.0.1

---

Workflow Release Completo

# 1. Preparazione release su branch develop
git checkout develop
git pull origin develop

# 2. Verifica stato
git log --oneline -5
git status

# 3. Merge in main
git checkout main
git pull origin main
git merge develop

# 4. Tag release
git tag -a v1.2.0 -m "Release version 1.2.0

Nuove funzionalità:
- Feature X
- Feature Y

Bugfix:
- Fix issue #123
- Fix issue #456
"

# 5. Push tutto
git push origin main
git push origin v1.2.0

# 6. Crea release su Forgejo
# (via web UI, carica binari, note rilascio)

---

Confrontare Tag

# Diff tra due tag
git diff v1.0.0 v1.1.0

# Commits tra due tag
git log v1.0.0..v1.1.0 --oneline

# Statistiche tra tag
git diff --stat v1.0.0 v1.1.0

---

Opzioni Comuni

git tag

Opzione	Descrizione
-a	Tag annotato
-m "msg"	Messaggio tag
-l "pattern"	Lista con pattern
-n	Mostra messaggi
-d	Elimina tag

git push

Opzione	Descrizione
origin <tag>	Push tag specifico
--tags	Push tutti i tag
--follow-tags	Solo tag annotati
--delete <tag>	Elimina tag remoto

---

Best Practices

✅ Usa tag annotati per release (-a)
✅ Segui Semantic Versioning (vMAJOR.MINOR.PATCH)
✅ Tagga sempre su main/master
✅ Messaggi tag dettagliati con changelog
✅ Push tag dopo verifica
❌ Non riutilizzare tag (elimina e ricrea se sbagliato)
❌ Non modificare tag pushati

---

🔗 Collegamenti

• Precedente: ← Sincronizzazione
• Prossimo: Stash →
• Indice: ← Torna all'indice

---

📝 Riepilogo comandi

# CREARE TAG
git tag v1.0.0                      # Lightweight
git tag -a v1.0.0 -m "Release"      # Annotated
git tag -a v0.9.0 abc123            # Su commit specifico

# LISTARE TAG
git tag                             # Tutti
git tag -l "v1.*"                   # Con pattern
git tag -n                          # Con messaggi
git show v1.0.0                     # Dettagli tag

# ELIMINARE TAG
git tag -d v1.0.0                   # Locale
git push origin --delete v1.0.0     # Remoto

# PUSH TAG
git push origin v1.0.0              # Tag specifico
git push origin --tags              # Tutti i tag
git push origin --follow-tags       # Solo annotati

# CHECKOUT TAG
git checkout v1.0.0                 # Detached HEAD
git checkout -b hotfix v1.0.0       # Branch da tag