Messaggi di commit Git: regole, esempi e convenzioni

Perché un messaggio di commit Git è importante

Un messaggio di commit spiega le tue modifiche a chi leggerà il codice in seguito, incluso il te del futuro.

Tra tre mesi non ricorderai perché hai rifattorizzato quella pipeline di dati o perché sei passato da pandas a polars per un'operazione specifica. Il tuo messaggio di commit è l'unico resoconto del tuo ragionamento. Senza, resti a indovinare o a scavare tra thread Slack e ticket JIRA.

Ecco qualche altra ragione concreta per cui il messaggio di commit conta.

Le code review scorrono più veloci con messaggi chiari. Chi revisiona può scansionare il messaggio, capirne l'intento e concentrarsi sul fatto che l'implementazione lo rispetti. Messaggi vaghi costringono i revisori a fare il reverse engineering del tuo pensiero dal solo diff.

Anche il debugging diventa più facile. Quando compare un bug, userai git log o git blame per risalire a quando è stato introdotto il codice problematico. Un messaggio come "fix authentication bug" non dice nulla. Un messaggio come "fix token expiration check in auth middleware" ti porta dritto al problema.

La collaborazione di team dipende da una cronologia leggibile. Quando qualcuno si unisce al progetto o riprende il tuo lavoro, leggerà i commit per capire come si è evoluta la codebase. Messaggi chiari trasformano la cronologia Git in documentazione che aiuta davvero.

In sintesi, un messaggio descrittivo richiede 15-30 secondi da scrivere, ma fa risparmiare ore di confusione in futuro.

Principi base di un buon messaggio di commit Git

I buoni messaggi di commit seguono pochi semplici principi, e basta.

Scrivi per i lettori del futuro

Il tuo messaggio di commit non è per te adesso: è per chi lo leggerà tra sei mesi.

Potrebbe essere un nuovo membro del team che prova a capire perché la codebase funziona in un certo modo. Potresti essere tu che cerchi di ricordare perché hai preso una certa decisione. In ogni caso, non avranno il contesto che hai oggi.

Concentrati su intento e motivazioni, non solo su cosa è cambiato. Il diff mostra cosa è cambiato. Il tuo messaggio dovrebbe spiegare perché è cambiato e quale problema risolve.

Sii chiaro e conciso

Messaggi brevi e descrittivi sono più facili da scansionare quando cerchi tra decine di commit.

Un messaggio come "add caching" è vago. Un messaggio come "add Redis caching for API responses" ti dice esattamente cosa è successo. Lo leggi in git log --oneline e capisci subito cosa fa il commit.

La riga d'oggetto dovrebbe rispondere: cosa fa questo commit? Se ti servono più di 50-60 caratteri per rispondere, probabilmente stai raggruppando troppe modifiche in un unico commit.

Sii coerente

La coerenza nel repository rende la cronologia prevedibile e più facile da leggere.

Quando ogni commit segue lo stesso formato, puoi scorrere rapidamente la cronologia. Sai dove cercare il tipo di modifica, l'ambito e la descrizione. I team che applicano formati coerenti possono anche automatizzare attività come generare changelog o filtrare i commit per tipo.

Scegli uno stile e rispettalo. Se il tuo team usa l'imperativo al presente, non passare a caso al passato.

Spiega cosa e perché (non come)

Il codice mostra come hai risolto il problema. Il messaggio di commit dovrebbe spiegare qual era il problema e perché hai scelto questa soluzione.

Non scrivere "refactored load_data() to use list comprehension instead of for loop." Scrivi "speed up data loading by 40% for large CSV files." Il primo descrive il cambio di codice. Il secondo spiega l'impatto.

Aggiungi contesto quando aiuta i lettori futuri a capire la tua decisione. Se hai provato tre approcci prima di scegliere questo, menzionalo. Se c'è un bug report o una decisione di design correlata, riferiscila.

La struttura di un messaggio di commit Git

La maggior parte dei messaggi di commit Git segue una struttura standard in tre parti: riga d'oggetto, corpo e footer.

Riga d'oggetto

La riga d'oggetto è un riepilogo su una riga che compare in git log --oneline e negli elenchi delle pull request.

Tienila sotto i 50 caratteri se possibile, massimo 72. Questo limite garantisce la corretta visualizzazione nell'output del terminale e nell'interfaccia di GitHub senza troncamenti. Se non riesci a riassumere in 50 caratteri, probabilmente stai descrivendo troppe modifiche in un solo commit.

Usa l'imperativo: scrivi "add feature" invece di "added feature" o "adds feature". Pensa di completare la frase "Se applicato, questo commit...". Quindi "Se applicato, questo commit aggiunge la cache Redis" scorre naturale, mentre "Se applicato, questo commit aggiunge la cache Redis" non funziona in inglese.

Esempi:

• fix null pointer exception in data loader

• add caching layer for API responses

• remove deprecated pandas functions

Corpo (quando serve)

Salta il corpo per modifiche semplici. Se la riga d'oggetto spiega pienamente il commit, hai finito.

Aggiungi un corpo quando devi spiegare perché hai fatto la modifica o fornire contesto utile ai lettori futuri. Lascia una riga vuota tra oggetto e corpo: Git la usa per separarli.

Il corpo dovrebbe rispondere a domande come: Quale problema risolve? Perché hai scelto questo approccio? Ci sono effetti collaterali o limiti? Hai considerato altre soluzioni?

Manda a capo a 72 caratteri per mantenere il testo leggibile nel terminale. La maggior parte degli editor può farlo automaticamente.

Esempio:

add Redis caching for API responses

API response times were hitting 2-3 seconds for repeated queries.
Added Redis with 5-minute TTL to cache query results. This drops
response time to ~50ms for cached queries.

Considered using in-memory cache but Redis lets us scale horizontally
if needed.

Footer (opzionale)

Usa il footer per riferimenti a issue, pull request o breaking change.

Se il tuo commit risolve una issue su GitHub, aggiungi Fixes #123 o Closes #456 nel footer. GitHub chiuderà automaticamente l'issue al merge del commit. Per breaking change, aggiungi BREAKING CHANGE: seguito da una descrizione di cosa è cambiato e come migrare.

Esempio:

remove support for Python 3.7

Python 3.7 reached end-of-life in June 2023. This commit drops
support and updates minimum version to Python 3.8.

BREAKING CHANGE: Python 3.7 users must upgrade to 3.8 or later.
Closes #789

Non ti serve un footer per la maggior parte dei commit: usalo solo quando colleghi riferimenti esterni o segnali breaking change.

Tipi comuni di messaggi di commit Git e quando usarli

Molti progetti usano prefissi di tipo commit per categorizzare a colpo d'occhio le modifiche.

Non serve memorizzare un elenco rigido di etichette. L'obiettivo è aiutare i lettori a identificare rapidamente il tipo di cambiamento senza leggere tutto il diff.

Ecco quattro categorie da conoscere:

• Le modifiche di feature introducono nuove funzionalità. Usa prefissi come feat: o add: quando costruisci qualcosa di nuovo: un nuovo endpoint API, una funzione di elaborazione dati o una feature lato utente. Esempio: feat: add CSV export for analysis results.

• Le correzioni di bug risolvono problemi esistenti. Usa fix: quando correggi un comportamento che non funzionava come previsto. Può essere di tutto, da una null pointer exception a calcoli errati nel tuo modello. Esempio: fix: handle missing values in preprocessing pipeline.

• Gli aggiornamenti della documentazione migliorano commenti, README o documentazione inline. Usa docs: quando non cambi il funzionamento del codice, ma lo spieghi meglio. Esempio: docs: add usage examples for data loader class.

• Refactoring e manutenzione migliorano la struttura del codice senza cambiarne il comportamento. Usa refactor: quando riorganizzi il codice per renderlo più pulito o mantenibile. Usa chore: per attività di routine come aggiornare le dipendenze o modificare le configurazioni di build. Esempi: refactor: extract validation logic into separate module o chore: update pandas to 3.0.0.

Scegli il tipo che descrive meglio la tua modifica e vai avanti: la coerenza conta più dell'etichetta "perfetta".

Regole per scrivere messaggi di commit Git migliori

Ecco una checklist di regole che renderanno i tuoi messaggi di commit più utili.

• Mantieni la riga d'oggetto sotto i 50 caratteri. Garantisce la corretta visualizzazione in git log --oneline, nell'elenco commit di GitHub e nel terminale senza troncamenti. Se non ci stai in 50 caratteri, punta a un massimo di 72.

• Usa l'imperativo. Scrivi "add feature" invece di "added feature" o "adds feature". La tua riga d'oggetto dovrebbe completare la frase "Se applicato, questo commit...". Così "Se applicato, questo commit aggiunge la cache" è corretto.

• Separa oggetto e corpo con una riga vuota. Git usa questa riga per distinguere tra riepilogo e spiegazione dettagliata. Senza, gli strumenti potrebbero mostrare il messaggio in modo errato.

• Evita il punto alla fine dell'oggetto. Risparmi caratteri e l'oggetto non è comunque una frase completa. Scrivi fix null pointer in loader invece di fix null pointer in loader.

• Metti l'iniziale maiuscola nella riga d'oggetto. Scrivi Add caching for API calls invece di add caching for API calls. Mantiene la cronologia coerente e professionale.

• Usa il corpo per spiegare il perché, non il cosa. Il diff mostra cosa è cambiato. Nel corpo spiega le motivazioni, gli approcci alternativi considerati e i trade-off.

• Manda a capo il corpo a 72 caratteri. Evita problemi di wrapping nel terminale e mantiene leggibili i messaggi nei vari strumenti.

• Rendi ogni commit atomico. Una modifica logica per commit. Se stai correggendo un bug e rifattorizzando codice, dividili in due commit con messaggi separati.

Esempi di buoni messaggi di commit Git

Ecco esempi reali di come dovrebbero apparire buoni messaggi di commit in diversi scenari.

Una correzione semplice

fix: handle NaN values in feature engineering

The preprocessing pipeline crashed when encountering NaN values
in the 'age' column. Added fillna() with median imputation before
scaling features.

Funziona perché identifica il problema (crash con NaN), spiega dove è avvenuto (pipeline di preprocessing, colonna age) e descrive la soluzione (imputazione mediana).

Una nuova feature

feat: add model performance tracking to MLflow

Added automatic logging of model metrics, parameters, and artifacts
to MLflow after each training run. This replaces our manual CSV
logging and makes experiment comparison much easier.

Metrics tracked: accuracy, precision, recall, F1 score
Training time also logged for performance monitoring.

I commit di feature spiegano cosa hai costruito, perché è utile e dettagli che aiutano a capire la portata della modifica.

Un refactor

refactor: split data_loader.py into separate modules

Moved dataset classes to datasets.py, transformation logic to
transforms.py, and utility functions to utils.py. The original
file was 800+ lines and hard to navigate.

No behavior changes - all tests still pass.

I messaggi di refactor devono chiarire che non hai cambiato la funzionalità, solo la struttura. La nota "all tests still pass" rassicura i revisori.

Un aggiornamento di documentazione

docs: add examples for custom loss functions

Previous documentation showed only built-in loss functions.
Added three examples: weighted cross-entropy, focal loss, and
custom regression loss with L1 regularization.

Each example includes code and explanation of when to use it.

I commit di documentazione dovrebbero spiegare cosa hai documentato e perché serviva.

Riferimento a un'issue o ticket

fix: prevent memory leak in batch processing

Large datasets caused memory usage to grow unbounded during batch
processing. The issue was holding references to processed batches
in the results list.

Changed to yield results instead of accumulating them in memory.
Memory usage now stays constant regardless of dataset size.

Fixes #247

Quando citi un'issue, includi abbastanza contesto da capire la correzione senza aprire il ticket. Fixes #247 in fondo dice a GitHub di chiudere automaticamente l'issue quando si fa merge.

Tutti gli esempi seguono lo stesso schema: inizia da cosa è cambiato, spiega il perché, aggiungi contesto utile ai lettori futuri e riferimenti a issue quando rilevanti.

Conventional Commits come standard per i messaggi di commit Git

Conventional Commits è un formato diffuso che aggiunge struttura ai messaggi di commit tramite un semplice schema di prefissi.

Formato base

Il formato è: type(scope): description.

Il tipo descrive il genere di modifica che stai facendo: feat per feature, fix per bugfix, docs per documentazione, refactor per ristrutturazione del codice e così via. Lo scope è opzionale e specifica quale parte della codebase è cambiata, come (auth) o (api). La description spiega cosa hai fatto.

Esempi:

feat(api): add endpoint for batch predictions
fix(auth): prevent token expiration edge case
docs(readme): add installation instructions for Windows
refactor(data): extract validation logic to separate module

Tieni presente che è una convenzione, non un requisito. A Git non importa se usi questo formato. Conta soprattutto la decisione di team su come strutturare i messaggi per coerenza e strumenti.

Quando i Conventional Commits sono utili

I team che automatizzano i processi di rilascio traggono il massimo valore dai Conventional Commits.

Gli strumenti possono analizzare la cronologia e generare automaticamente i changelog. Quando tagghi una release, lo strumento scansiona i commit dall'ultimo rilascio, li raggruppa per tipo (feat, fix, docs) e crea un changelog formattato. Risparmi il lavoro manuale di tracciare cosa è cambiato tra le versioni.

I Conventional Commits supportano anche l'automazione del versioning semantico. Se tutti i commit dall'ultimo rilascio sono fix, lo strumento incrementa la patch (1.2.3 → 1.2.4). Se hai aggiunto feature, incrementa la minor (1.2.3 → 1.3.0). Le breaking change fanno salire la major (1.2.3 → 2.0.0).

Ma se il tuo team non usa release automatizzate o generazione di changelog, i Conventional Commits potrebbero essere eccessivi. La struttura aiuta più le macchine che gli umani: tienilo a mente.

Errori comuni nei messaggi di commit Git da evitare

Anche sviluppatori esperti a volte sbagliano a scrivere i messaggi di commit, ma spesso è più pigrizia che mancanza di conoscenza.

Ecco un paio di errori da evitare.

Messaggi vaghi o generici

Messaggi come "fix bug" o "update code" non dicono nulla a chi leggerà in futuro.

Quando cerchi una modifica specifica con git log, scorrerai decine di commit. Un messaggio "fix bug" ti costringe ad aprire il diff e leggere il codice per capire cosa è stato corretto. Un messaggio "fix null pointer in data preprocessing" ti dice subito se è il commit che cerchi.

Messaggi generici fanno perdere tempo a tutti. Se non ricordi abbastanza bene cosa hai cambiato da scrivere un messaggio specifico, probabilmente non dovresti ancora fare commit.

Mescolare modifiche non correlate

Un commit dovrebbe contenere una sola modifica logica.

Se sistemi un bug e rifattorizzi codice non correlato nello stesso commit, rendi più difficili le review e inutile git bisect. Se quel commit introduce una regressione, qualcuno dovrà districare quale parte l'ha causata. Se vogliono revertare solo la correzione, non possono: annullerebbero anche il refactor.

Dividi sempre le modifiche in commit separati. Correggi il bug in un commit, rifattorizza in un altro. Ogni commit dovrebbe poter essere revertato indipendentemente senza rompere la codebase.

Se hai già mescolato modifiche in locale, usa git add -p per selezionare porzioni di file e committarle in blocchi logici.

Lasciare messaggi di lavoro in corso

Commit con messaggi come "WIP" o "temp fix" vanno bene in locale ma non dovrebbero finire sulla branch principale.

Prima di fare merge della tua feature branch, pulisci la cronologia dei commit. Squasha i commit WIP in commit significativi con messaggi adeguati. Riscrivi "asdf" e "trying something" in descrizioni che spieghino cosa hai fatto davvero.

Usa git rebase -i per combinare commit, riscrivere messaggi e riordinare le modifiche prima del push. Il tuo team dovrebbe vedere una cronologia pulita di cosa è cambiato e perché, non il tuo processo di debug.

Best practice per i team sui messaggi di commit Git

Se il tuo team vuole rendere davvero utile la cronologia Git, serve coerenza. Ecco alcune best practice da seguire.

Concorda presto uno stile condiviso. Decidete se usare i Conventional Commits, un formato personalizzato o solo un set di regole di base. Scegliete un approccio e applicatelo in tutto il team. Se metà dei commit dicono "feat: add feature" e l'altra metà "Added new feature", la cronologia diventa più difficile da scansionare e l'automazione può rompersi.

Lo stile conta meno della sua applicazione uniforme. Alcuni team preferiscono l'imperativo al presente ("add feature"), altri il passato ("added feature"). Entrambi funzionano se usati in modo coerente.

Documenta le convenzioni in un luogo accessibile. Aggiungi un file CONTRIBUTING.md nel repository che spieghi il formato dei messaggi di commit con esempi. Includilo nell'onboarding dei nuovi membri. Quando qualcuno chiede "come formatto questo commit?", indirizzalo alla documentazione invece di rispiegare tutto.

La documentazione dovrebbe coprire il formato base che usate, quando aggiungere un corpo rispetto al solo oggetto, come riferire issue o ticket e qualche esempio reale dal vostro repo.

Usa i messaggi di commit durante le code review. Buoni messaggi rendono le review più rapide e mirate. Chi revisiona può leggere i messaggi per capire la progressione delle modifiche prima di entrare nel codice.

Durante la review, controlla i messaggi come controlli il codice. Se un messaggio è vago o fuorviante, chiedi di riscriverlo prima del merge. Una PR con commit chiari è più facile da rivedere, da revertare se serve e da capire in seguito.

Conclusione

Un messaggio di commit chiaro richiede 30 secondi da scrivere ma fa risparmiare ore di confusione dopo.

Pensa alla cronologia dei commit come a documentazione che vive con il tuo codice. Quando scrivi "fix bug" invece di "fix null pointer in data preprocessing", fai perdere tempo a chi leggerà quel commit in futuro, te compreso.

Tratta i messaggi di commit come il codice. Se non manderesti in produzione codice sciatto e senza commenti, non mandare nemmeno messaggi di commit scadenti. Usa l'imperativo, tieni l'oggetto sotto i 50 caratteri, spiega il perché nel corpo quando serve e rendi ogni commit atomico.

Ora sai come scrivere commit significativi. Per fare un salto di livello, iscriviti al nostro corso Intermediate Git.