git commit: messaggi che durano nel tempo

Un commit è una decisione salvata nella storia. Il messaggio deve aiutare chi leggerà tra tre settimane, non solo chi sta facendo push adesso.

Un buon messaggio non ripete il diff. Il diff dice cosa è cambiato. Il messaggio deve spiegare l’intento, il perimetro e, quando serve, il motivo.

Perché questa lezione conta

La storia Git è uno strumento di debug, review e manutenzione. Se i commit si chiamano fix, update, varie, finale, la storia non racconta nulla. Quando compare un bug, git log, git blame e git bisect diventano meno utili.

Scrivere bene i commit non è formalismo: è investimento sul futuro del progetto.

Obiettivo operativo

Alla fine della lezione devi saper scrivere messaggi chiari, distinguere oggetto e body, usare Conventional Commits quando serve e configurare un template.

Struttura base

Formato classico:

Oggetto breve in imperativo

Body opzionale che spiega perché, contesto e trade-off.

Esempio:

Valida email prima della registrazione

La API accettava stringhe vuote e demandava l'errore al database.
La validazione nel caso d'uso rende il messaggio utente più chiaro
e impedisce log rumorosi in produzione.

La prima riga dovrebbe essere leggibile in git log --oneline. Il body serve quando il motivo non è ovvio dal diff.

Imperativo

Molti team usano l’imperativo:

Aggiungi controllo permessi
Rimuovi fallback legacy
Correggi parsing date

Non è una regola morale. È utile perché completa mentalmente la frase:

Questo commit, se applicato, ...

”… correggi parsing date” suona coerente.

Cattivi messaggi

fix
update
wip
modifiche
prova
sistemato

Sono messaggi inutili perché non rispondono a nessuna domanda. Se devi usare wip, probabilmente il commit non è pronto per essere condiviso oppure va squashato prima della PR.

Conventional Commits

Formato:

tipo(scope): descrizione

Esempi:

feat(auth): aggiungi login con magic link
fix(api): gestisci timeout del provider
docs(readme): documenta variabili ambiente
refactor(cart): separa calcolo totale
test(checkout): copri doppio submit

Serve quando il team vuole changelog automatici, versioning semantico o regole uniformi in CI. Non è obbligatorio per ogni progetto, ma è molto utile quando ci sono più contributor.

Body: quando scriverlo

Scrivi body quando:

1. il cambiamento ha trade-off;
2. il diff non spiega il motivo;
3. stai correggendo un bug non ovvio;
4. c’è un riferimento a issue o incidente;
5. stai cambiando comportamento pubblico;
6. stai rimuovendo codice che sembrava utile.

Non serve body per ogni typo o piccola modifica evidente.

Template

Configura un template:

git config --global commit.template ~/.gitmessage

Esempio:

tipo(scope): oggetto breve

Perché:

Cosa cambia:

Verifiche:

Il template non deve diventare burocrazia. Serve a ricordarti le informazioni che spesso mancano.

Commit atomici e messaggi

Un messaggio buono non salva un commit confuso. Se devi scrivere:

fix: correggi login, aggiorna navbar e formatta file

il problema non è il messaggio. Il problema è il commit.

Prima separa lo stage, poi scrivi un messaggio preciso.

Laboratorio guidato

Prendi gli ultimi 10 commit di un tuo repo:

git log --oneline -10

Classificali:

1. chiaro senza aprire diff;
2. comprensibile solo col diff;
3. inutile;
4. troppo ampio.

Riscrivi i cinque peggiori come se fossero commit nuovi. Non devi riscrivere davvero la storia: l’esercizio è imparare a vedere cosa manca.

Output atteso

Produci:

1. un template .gitmessage;
2. 5 esempi prima/dopo;
3. una regola di team su Conventional Commits: sì, no, o solo per release.

Errori comuni

Descrivere solo il cosa. Il diff lo mostra già.

Fare body enorme per commit banali. La qualità è informazione utile, non lunghezza.

Usare Conventional Commits senza capirne lo scopo. Se non genera changelog o regole, può diventare solo decorazione.

Mescolare intenzioni. Messaggi lunghi spesso nascondono commit troppo grandi.

Checklist di verifica

• la prima riga è leggibile in --oneline;
• il body spiega il perché quando serve;
• il messaggio non promette più di quanto il diff faccia;
• i commit rumorosi vengono squashati o riscritti prima della PR;
• il team ha una convenzione condivisa.

Collegamenti

• Modulo: Lavorare in solitario: i comandi quotidiani — lezione 7 del corso.
• Conventional Commits torna nel modulo 6.