modulo 07 / lezione 32

Casi reali, debugging della storia, recupero

git blame e archeologia del codice

Capire chi e quando ha scritto una riga, e perché, senza trasformarlo in caccia alle streghe.

60 minGit e controllo versione

git blame e archeologia del codice

git blame mostra, per ogni riga di un file, l’ultimo commit che l’ha modificata. È uno strumento di contesto: serve a capire quando una decisione è entrata nel codice, quali file erano coinvolti e quale discussione cercare in PR o issue.

Il nome è infelice. Usarlo bene significa cercare storia, non colpe.

Perché questa lezione conta

Quando trovi una riga sospetta, il diff attuale non basta. Devi sapere se quella riga nasce da un bugfix urgente, da una migrazione, da una compatibilità con un cliente o da un refactor incompleto.

blame è il primo passo di archeologia del codice: parte da una riga e ti porta a commit, PR, issue e decisioni.

Obiettivo operativo

Alla fine della lezione devi saper usare git blame su file e intervalli, ignorare commit di formattazione, seguire l’evoluzione di una funzione con git log -L e trasformare l’indagine in una spiegazione tecnica utile.

Comandi base

git blame src/auth.ts
git blame -L 42,60 src/auth.ts
git blame -w src/auth.ts

-L limita l’output a un intervallo di righe. -w ignora cambiamenti di whitespace, utile dopo formattazioni automatiche.

Per vedere il commit:

git show <sha>
git show --stat <sha>

Guarda messaggio, diff, file toccati e data. Poi cerca la PR associata se il progetto usa merge commit o riferimenti a issue.

Ignorare commit di formattazione

Se un commit ha solo formattato il repository, blame può diventare poco utile. Crea un file:

.git-blame-ignore-revs

Dentro inserisci gli SHA dei commit da ignorare:

abc1234567890abcdef
def4567890abcdef123

Poi usa:

git blame --ignore-revs-file .git-blame-ignore-revs src/auth.ts

Puoi configurarlo nel repo:

git config blame.ignoreRevsFile .git-blame-ignore-revs

Questo file va versionato, così tutto il team legge la stessa storia.

Seguire una funzione nel tempo

Per vedere come una funzione è cambiata:

git log -L :verifyEmail:src/auth.ts

Oppure per intervallo:

git log -L 42,80:src/auth.ts

git log -L mostra l’evoluzione del blocco nel tempo. È più informativo di un singolo blame quando vuoi capire perché una condizione è stata aggiunta, rimossa e poi reintrodotta.

Metodo di indagine

Usa una sequenza precisa:

  1. individua riga o funzione sospetta;
  2. esegui git blame -L;
  3. apri il commit con git show;
  4. guarda file collegati nello stesso commit;
  5. cerca PR o issue;
  6. confronta con git log -L;
  7. scrivi una nota di contesto prima di modificare.

La nota può essere breve:

La validazione è stata introdotta in abc123 per gestire provider legacy.
La PR collegata cita utenti senza email verificata.
Il fix attuale deve preservare quel caso.

Cultura di team

Non usare blame per chiedere “perché hai scritto questa cosa?” a freddo. Chiedi: “Ho visto che questa riga nasceva nel commit X per il caso Y; quel vincolo esiste ancora?”.

La differenza cambia il tono e migliora la qualità della risposta.

Laboratorio guidato

Scegli un file reale complesso:

  1. identifica tre righe critiche;
  2. usa git blame -L per ciascuna;
  3. apri i commit collegati;
  4. segui una funzione con git log -L;
  5. crea o aggiorna .git-blame-ignore-revs se trovi formattazioni rumorose;
  6. scrivi una spiegazione di 10 righe per un nuovo collega.

Output atteso

Una scheda di archeologia:

File:
Righe:
Commit rilevanti:
Decisione originale:
Vincoli ancora validi:
Rischi se cambiamo:
Prossima modifica consigliata:

Errori comuni

Fermarsi al nome dell’autore. L’autore non basta: servono commit, contesto e vincoli.

Ignorare commit di formatting. Possono nascondere la storia utile.

Non leggere il diff completo. Una riga spesso ha senso solo insieme ad altri file.

Cambiare senza capire il perché. Rischi di reintrodurre bug già risolti.

Checklist di verifica

  • so usare git blame -L;
  • so ignorare commit rumorosi con .git-blame-ignore-revs;
  • so usare git log -L;
  • so trasformare blame in contesto tecnico;
  • so fare domande di review senza personalizzare il problema.

Esercizi

Base · facile

Scopri chi ha modificato per ultimo le righe di un file e in quale commit.

Soluzione 
git blame file.js
# a1b2c3d (Anna 2025-03-01 12:00 12) const x = calcola();

git blame annota ogni riga del file con l’ultimo commit che l’ha toccata, l’autore e la data. Serve a capire quando e perché una riga è arrivata, non a dare colpe.

Intermedio · medio

Limita il blame a un intervallo di righe e segui una riga anche quando il codice è stato spostato. Spiega l’uso reale.

Soluzione 
git blame -L 40,60 file.js     # solo le righe 40-60
git blame -M file.js           # segue le righe spostate dentro il file
git blame -C file.js           # segue anche le righe copiate da altri file

-L restringe l’indagine alla zona che ti interessa. -M/-C evitano che un semplice spostamento/copia attribuisca la riga a chi l’ha solo riorganizzata: così risali al commit che ha davvero scritto quella logica. Uso tipico: capire la motivazione dietro una riga sospetta prima di modificarla.

Sfida · difficile

Dal blame, risali al commit di una riga e leggine il contesto completo (messaggio e diff). Spiega come combinare blame e log per l’archeologia del codice.

Soluzione 
git blame file.js              # trova l'hash della riga sospetta
git show a1b2c3d              # messaggio + diff completo di quel commit
git log -L 50,50:file.js     # l'intera storia di evoluzione di una singola riga

Il blame dà il “chi/quando” della riga attuale; git show <hash> aggiunge il perché (messaggio e modifiche dell’intero commit); git log -L ricostruisce tutta la storia di quella riga nel tempo. Insieme trasformano una riga misteriosa in una vicenda comprensibile: utile prima di cambiare codice che non hai scritto, per non rompere un’intenzione nascosta.

Collegamenti

  • Modulo: Casi reali, debugging della storia, recupero - lezione 32 del corso.
  • Si collega a debugging, refactor sicuro e code review.