Git: Gestione dei Tag (Tagging)

Come nella maggior parte dei sistemi di controllo versione (VCS), Git consente di associare un’etichetta (tag) a specifici punti della cronologia di un repository.

Questa funzionalità è comunemente utilizzata per identificare rilasci ufficiali del software (ad esempio v1.0, v2.0, ecc.), ma può anche servire a marcare revisioni significative per motivi organizzativi o di audit.

1. Elenco dei Tag Esistenti

Per visualizzare i tag presenti in un repository Git, il comando di riferimento è:
git tag

FIG 1 - Visualizza tag presenti

L’output mostra i tag in ordine alfabetico. L’ordinamento non riflette la sequenza temporale dei rilasci o la loro importanza, ma è puramente lessicografico.

Nei progetti complessi, il numero di tag può essere molto elevato (il repository ufficiale di Git, ad esempio, contiene centinaia di etichette).

Per filtrare i risultati in base a un criterio, è possibile utilizzare le opzioni -l o --list insieme a una wildcard.

Esempio

Se si desidera visualizzare esclusivamente i tag relativi alla versione 4.7, si può eseguire:

$ git tag -l "v4.7*"

FIG 2 - Filtrare i tag

Nota Importante

L’utilizzo di git tag senza argomenti restituisce implicitamente l’elenco completo dei tag.
Se invece si utilizza un pattern (ad esempio "v4.7*"), è obbligatorio specificare -l o --list.

2. Tipologie di Tag in Git

Git mette a disposizione due principali categorie di tag:

• Leggeri (lightweight tag).
• Annotati (annotated tag).

Entrambe le tipologie servono a collegare un commit a un’etichetta significativa, ma si differenziano profondamente in termini di struttura, metadati e finalità d’uso.

Tag Annotati (Annotated Tags)

I tag annotati sono oggetti completi, salvati nel database di Git con un proprio checksum.

Caratteristiche principali:

• Contengono metadati come autore (tagger), email, data.
• Includono un messaggio di tagging, utile per descrivere lo scopo o il contenuto della release.
• Possono essere firmati digitalmente con GNU Privacy Guard (GPG) per garantire autenticità e integrità.
• Sono generalmente considerati la scelta raccomandata per i rilasci ufficiali.

I tag annotati rappresentano la modalità più completa e raccomandata per contrassegnare uno specifico punto nella storia di un repository Git. Essi non solo puntano a un commit, ma contengono anche metadati aggiuntivi che ne arricchiscono l’informazione e ne garantiscono l’autenticità.

Per creare un tag annotato, si utilizza l’opzione -a del comando git tag, accompagnata da un messaggio descrittivo tramite l’opzione -m.

Esempio

git tag -a v1.0 -m "Release ufficiale versione 1.0"

FIG 3 - Creazione di un Tag Annotato

Per ottenere dettagli su un tag annotato, incluso il commit a cui si riferisce, si utilizza il comando git show.

git show v1.0

FIG 4 - git show

Come si può notare, l’output mostra:

• informazioni sul tag (nome, autore del tag, email, data, messaggio di annotazione),
• dettagli sul commit associato (hash, autore, data, messaggio del commit).

Vantaggi dei Tag Annotati

• Tracciabilità: contengono informazioni su chi ha creato il tag e quando.
• Documentazione: permettono di associare un messaggio descrittivo che contestualizza la versione.
• Sicurezza: possono essere firmati digitalmente con GPG, garantendo autenticità e integrità.
• Professionalità: sono la scelta ideale per marcare rilasci ufficiali o milestone significative.

Tag Leggeri (Lightweight Tags)

Oltre ai tag annotati, Git consente la creazione di tag leggeri (lightweight tags), una modalità più semplice e meno strutturata per marcare uno specifico commit nella storia del repository.

A differenza dei tag annotati, i tag leggeri non includono metadati aggiuntivi: essi rappresentano semplicemente un puntatore diretto a un commit, equivalente a salvare l’hash di quel commit in un riferimento con un nome leggibile.

Un tag leggero rappresenta il tipo più semplice di tag in Git.

• È sostanzialmente un puntatore immutabile a un commit specifico, molto simile a un branch che non evolve.
• Non contiene metadati aggiuntivi: né autore, né data, né messaggio.
• È utile per:
  - contrassegnare rapidamente una revisione
  - definire marcature temporanee
  - operazioni di test o debugging.

Per creare un tag leggero è sufficiente eseguire il comando git tag specificando il nome del tag, senza utilizzare le opzioni -a (annotato), -s (firmato) o -m (messaggio). 

Esempio

git tag v1.0.0

In questo caso, il tag v1.0.0 punta semplicemente al commit corrente, senza ulteriori informazioni.

A differenza dei tag annotati, l’uso di git show su un tag leggero non fornisce informazioni aggiuntive (autore del tag, data, messaggio). Mostra esclusivamente i dettagli del commit a cui il tag fa riferimento.

3. Aggiungere un Tag retroattivamente in Git

In alcuni casi può accadere di dimenticare di creare un tag al momento opportuno, ad esempio in corrispondenza di un rilascio o di una milestone importante. Fortunatamente, Git consente di aggiungere un tag retroattivo a un commit già presente nella cronologia, anche se non si tratta dell’ultimo.

Scenario di Partenza

Supponiamo che la cronologia dei ommit sia simile a quella mostrata in FIG 5 dal comando

git log --pretty=oneline

FIG 5 - git log --pretty=oneline

Supponiamo di voler aggiungere un tag alla versione v1.0, corrispondente al commit con messaggio Modifica Projects1.cs  (hash abbreviato 925e858).

Per creare un tag annotato riferito a un commit precedente, è sufficiente specificarne l’hash (anche parziale, purché univoco) al termine del comando:

git tag -a v1.0 925e858 -m "version 1.0"

FIG 6 - Creazione del Tag Retroattivo

Per ottenere informazioni dettagliate sul tag e sul commit associato, è possibile usare:

git show v1.0

FIG 7 - git show

L’output mostra sia i metadati del tag (autore, data, messaggio) sia i dettagli del commit referenziato.

4. Condivisione dei Tag in Git

Per impostazione predefinita, il comando git push non trasferisce automaticamente i tag al repository remoto. Pertanto, una volta creati, è necessario eseguire un’operazione esplicita di push per renderli disponibili ad altri collaboratori. Questo comportamento differisce dai branch, i quali vengono aggiornati automaticamente in seguito a un push.

Pubblicazione di un Singolo Tag

Per condividere un tag specifico con il server remoto, si utilizza la seguente sintassi:

git push origin <tagname>

Ad esempio:

git push origin v1.0

FIG 8 - Push di un singolo tag

In questo esempio, il tag v1.0 viene trasferito correttamente sul repository remoto origin.

Pubblicazione di Tutti i Tag

Qualora sia necessario trasferire più tag contemporaneamente, Git fornisce l’opzione --tags, che invia tutti i tag locali non ancora presenti sul server remoto:

git push origin --tags

FIG 9 - Push di tutti i tag

Dopo questa operazione, chiunque effettui un git clone o un git pull riceverà anche tutti i tag pubblicati.

Differenze tra Tipologie di Tag

È importante ricordare che:

• Il comando git push invia sia i tag lightweight che quelli annotati.
• Per trasferire solo i tag annotati, è possibile utilizzare l’opzione --follow-tags:
  git push origin --follow-tags
  In questo modo, vengono pubblicati soltanto i tag associati a commit presenti nella cronologia del push e che siano stati creati come tag annotati.

Verificare tag disponibili sul repository remoto

Per verificare i tag disponibili sul repository remoto dopo un push, è possibile utilizzare il comando

git ls-remote --tags origin

 

FIG 10 - Tag presenti sul repository remoto

5. Eliminazione dei Tag in Git

In Git, i tag possono essere eliminati sia localmente che sul repository remoto. È importante distinguere le due operazioni, poiché la rimozione in locale non influisce automaticamente sul server remoto, e viceversa.

Eliminazione di un Tag Locale

Per eliminare un tag nel repository locale, si utilizza il comando:

git tag -d <tagname>

Ad esempio:

git tag -d v1.0-lw

FIG 11 - Eliminazione di un tag locale

In questo caso, il tag v1.0-lw viene eliminato solo dal repository locale.

Tuttavia, se il tag era già stato pubblicato su un remoto (es. origin), esso continuerà ad esistere sul server finché non verrà rimosso manualmente.

Eliminazione di un Tag Remoto

Per rimuovere un tag da un repository remoto, Git mette a disposizione due approcci.

1. Utilizzo della sintassi con refs/tags
   git push <remote> :refs/tags/<tagname>
   
   Esempio
   git push origin :refs/tags/v1.0-lw
   
   In questa sintassi, il valore nullo (:) viene "spinto" verso il riferimento remoto del tag, ottenendo come effetto la sua cancellazione.
   
   

   

   FIG 12 - Eliminazione di un Tag Remoto refs-tags

   
   
2. Utilizzo dell’opzione --delete (più intuitivo)
   git push <remote> --delete <tagname>
   
   Esempio:
   git push origin --delete v1.0.1
   
   
   Questa modalità è generalmente preferita, poiché risulta più leggibile e intuitiva rispetto alla precedente.
   
   

   

   FIG 13 - Eliminazione di un Tag Remoto --delete

   
   

6. Visualizzazione del Contenuto di un Tag con git checkout

In Git, i tag rappresentano riferimenti immutabili a specifici commit. Per visualizzare lo stato del progetto associato a un determinato tag, è possibile utilizzare il comando:

git checkout <tagname>

Ad esempio:

git checkout v1.0

FIG 14 - git checkout

Lo stato Detached HEAD

Effettuando un checkout diretto su un tag, Git posiziona il repository in modalità detached HEAD.

In questo stato:

1. È possibile esplorare i file e compilare il progetto esattamente come era al momento del commit taggato.
2. È consentito creare commit, ma questi non saranno collegati ad alcun branch, risultando raggiungibili solo tramite il loro hash SHA.
3. Se si esegue un nuovo git checkout senza aver salvato i commit, le modifiche saranno difficilmente recuperabili.

Esempio:

git checkout v1.0.1

FIG 15 - git checkout

Creazione di un Branch a partire da un Tag

Per lavorare su una versione storica (ad esempio correggere un bug in una release precedente), è consigliato creare un branch derivato dal tag:

git checkout -b <branchname> <tagname>

Esempio:

git checkout -b version2 v2.0

FIG 16 - Creazione di un Branch a partire da un Tag

In questo caso, il nuovo branch version2 viene creato a partire dal commit identificato dal tag v2.0. Eventuali nuovi commit saranno tracciati da questo branch e non andranno persi.

È importante ricordare che il branch si evolverà in maniera indipendente rispetto al tag:

• Il tag rimarrà un riferimento statico al commit originale.
• Il branch potrà avanzare con nuovi commit.

Git: Annullare le operazioni

Durante lo sviluppo, può capitare di voler annullare una modifica o correggere un errore. Git offre diversi strumenti per gestire queste situazioni, ma è fondamentale utilizzarli con cautela: alcune operazioni di undo non sono reversibili e, se usate in modo improprio, possono comportare la perdita definitiva di lavoro.

Correggere l’ultimo commit con --amend

Uno degli scenari più comuni si verifica quando si effettua un commit troppo presto, dimenticando di includere un file o inserendo un messaggio di commit errato. In questi casi, Git consente di sostituire l’ultimo commit con uno nuovo tramite l’opzione --amend:

git commit --amend

Git prende il contenuto dell’area di staging (index) e lo utilizza per generare un nuovo commit.

Se non sono state aggiunte nuove modifiche dallo scorso commit, verrà riaperto semplicemente l’editor dei messaggi di commit, consentendo di modificarlo.

Esempio pratico

Supponiamo di aver eseguito il commit e di esserci resi conto di aver dimenticato di inserire le modifiche in un file che volevamo aggiungere a questo commit. Possiamo rimediare aggiungendo il file con git add e rieseguire il commit con git commit --amend:

git commit -m "Initial commit"
git add file_dimenticato
git commit --amend

Il repository avrà un solo commit, che include anche file_dimenticato. Il commit precedente viene sovrascritto e sparisce dalla cronologia.

Aspetti importanti da considerare

• Sostituzione, non modifica 
  - Amend non aggiorna un commit già esistente ma lo sostituisce con un nuovo commit dotato di un nuovo identificativo (SHA-1).
  - Di fatto, è come se il commit precedente non fosse mai esistito.
• Pulizia della cronologia
  - L’opzione --amend è utile per evitare commit ridondanti.
• Limitazione: solo commit locali
  - È fortemente sconsigliato eseguire git commit --amend su commit già pubblicati (pushed) in un repository remoto. Infatti, l’operazione riscrive la cronologia e, se accompagnata da un git push --force, può creare conflitti e problemi per gli altri collaboratori.

Tabella di sintesi: git commit --amend

Scenario	Comando	Risultato
Modificare solo il messaggio di commit	git commit --amend (senza nuovi file in staging)	Sovrascrive il messaggio dell’ultimo commit
Aggiungere file dimenticati	git add file + git commit --amend	Crea un nuovo commit che sostituisce il precedente includendo anche file
Commit già pushato sul remoto	git commit --amend + git push --force	Sconsigliato: riscrive la cronologia e può rompere il lavoro dei collaboratori

Rimuovere un File dall’Area di Staging

Durante il lavoro quotidiano con Git, può capitare di inserire per errore più file nell’area di staging (index) utilizzando un comando troppo generico, come ad esempio:

git add *

In questo caso, se l’obiettivo era committare i file separatamente, è necessario rimuovere uno o più file dallo staging (unstaging), riportandoli allo stato di semplici modifiche nella working directory.

A partire dalla versione 2.23.0, Git ha introdotto il comando git restore, concepito come alternativa più intuitiva e leggibile rispetto a git reset per alcune operazioni di annullamento (undo).

L’obiettivo di questo nuovo comando è semplificare la sintassi e ridurre i rischi legati a usi impropri di git reset, che in passato potevano facilmente portare alla perdita involontaria di dati.

la differenza principale tra git restore e git reset HEAD sta nel loro scopo e nell'ambito d'azione:

• git restore è un comando moderno e più sicuro, ideato per ripristinare i file nello stato in cui si trovavano in una versione precedente. Agisce sulla working directory (area di lavoro) o sulla staging area (area di "preparazione" prima del commit), ma non modifica la cronologia dei commit. È l'ideale per annullare modifiche locali, che non sono ancora state salvate nella cronologia.
• git reset HEAD è un comando più vecchio, versatile e potente, che agisce primariamente sulla cronologia dei commit. Sposta il puntatore HEAD a un commit precedente, e di conseguenza, può influenzare l'area di staging e l'area di lavoro a seconda dell'opzione utilizzata (--soft, --mixed, o --hard). È uno strumento più "distruttivo" e va usato con cautela, specialmente su branch condivisi, perché modifica la storia del repository.

Identificare i file in staging con git status

Il comando git status non solo mostra lo stato della working directory e dell’area di staging, ma fornisce anche indicazioni utili su come annullare operazioni indesiderate.

Esempio pratico:

Per individuare il file da rimuovere all'area di staging

git status

FIG 1 - git status

Come si può notare da FIG 1 , Git suggerisce direttamente il comando corretto per rimuovere un file dallo staging.

git restore --staged <file>

Nel nostro caso, per rimuovere il file main.cs dallo staging il comando sarà

git restore --staged main.cs

FIG 2 - git restore --staged

Lo stesso risultato lo si ottiene con 

git reset HEAD <file>

Il comando git reset è spesso considerato pericoloso, poiché con opzioni come --hard può portare alla perdita definitiva di modifiche locali. Tuttavia, in questo scenario, l’uso di git reset HEAD è sicuro perché non modifica i contenuti della working directory ma agisce esclusivamente sull’indice, rimuovendo il file dallo staging.

Tabella di sintesi: Comandi per gestire lo staging

Comando	Effetto
git add file	Aggiunge un file all’area di staging
git reset HEAD file	Rimuove il file dallo staging, mantenendo le modifiche nella working directory
git restore --staged file	Alternativa moderna a git reset HEAD file, con la stessa funzione
git reset --hard	Pericoloso: annulla anche le modifiche nella working directory

 

Annullare le modifiche a un File

Può capitare di accorgersi che le modifiche apportate a un file non sono più necessarie e che si desidera ripristinare il contenuto all’ultima versione tracciata da Git (ossia l’ultima presente nell’area di staging o nel commit più recente).

In questi casi, Git mette a disposizione due comandi storicamente equivalenti, ma con differenze importanti: git restore (introdotto in Git ≥ 2.23.0) e git checkout (metodo tradizionale).

Esempio pratico con git restore

Supponiamo di aver modificato il file main.cs. Eseguiamo il comando

git status

FIG 3 - git status

Per annullare le modifiche non salvate:

git restore main.cs

Dopo il comando, il file torna allo stato dell’ultimo commit o staging, eliminando definitivamente i cambiamenti locali.

FIG 4 - git restore

Esempio pratico con git checkout

git checkout -- main.cs

Anche in questo caso il file viene ripristinato, cancellando le modifiche locali.

FIG 5 - git checkout

Differenze tra git restore e git checkout

Caratteristica	git restore	git checkout
Disponibilità	Introdotto in Git ≥ 2.23.0	Presente in tutte le versioni di Git
Obiettivo	Progettato specificamente per annullare modifiche ai file (working directory e staging)	Comando multifunzione (cambio branch, ripristino file, navigazione)
Chiarezza sintattica	Più leggibile e autoesplicativo (restore indica chiaramente lo scopo)	Sintassi più generica e meno intuitiva
Rischio di confusione	Ridotto: il comando è dedicato solo al ripristino	Elevato: git checkout gestisce operazioni molto diverse tra loro
Best Practice	Consigliato nei workflow moderni per annullare modifiche locali	Ancora valido, ma da usare con cautela per evitare ambiguità

Attenzione

• Entrambi i comandi cancellano in modo irreversibile le modifiche locali non ancora salvate in un commit.
• Prima di utilizzarli, è opportuno chiedersi se le modifiche possano essere utili in futuro.
• In alternativa, si può ricorrere a git stash o a un nuovo branch, salvando temporaneamente i cambiamenti senza perderli.

È importante ricordare che soltanto ciò che è stato effettivamente sottoposto a commit può essere recuperato; le modifiche non salvate andranno invece perse in maniera definitiva.

In Git, i dati oggetto di commit risultano quasi sempre recuperabili, anche qualora appartengano a rami successivamente eliminati oppure siano stati sovrascritti tramite l’opzione --amend. Tutte le modifiche non ancora committate e andate perse non potranno, con ogni probabilità, essere ripristinate.

Best Practice

• Usare git restore nei progetti moderni: più chiaro e meno soggetto a errori.
• Evitare git checkout -- <file> se non strettamente necessario: mantiene la retrocompatibilità, ma può confondere.
• Ricorrere a git stash o ai branch per soluzioni temporanee: ideale se non si vuole perdere il lavoro fatto.