Git Bisect: Trova il Commit che ha introdotto un bug
Una funzionalità ha funzionato ieri ma fallisce oggi. Impara come usare Git bisect per individuare il commit che ha introdotto una regressione, testare le revisioni automaticamente e indagare sul risultato in modo sicuro.
Un sito web funzionava la settimana scorsa. Oggi, il calcolo di un checkout è errato, un componente JavaScript non risponde più, oppure un endpoint PHP restituisce dati inattesi.
Sai che il bug è comparso in un punto qualsiasi della cronologia di Git, ma il repository contiene decine o centinaia di commit dall'ultima versione funzionante. Aprire ogni commit e leggere ogni diff raramente è la soluzione più rapida.
Git include uno strumento pensato esattamente per questa situazione: git bisect. Invece di esaminare ogni commit, utilizza una ricerca binaria per identificare la revisione che ha introdotto per primo il problema. Con un test affidabile, puoi automatizzare l'indagine.
In questo tutorial creerai un piccolo progetto PHP, introdurrai deliberatamente una regressione, la localizzerai con Git bisect e imparerai come applicare la stessa tecnica a progetti reali.
1. Come funziona Git bisect
Immagina che la tua applicazione funzionasse al commit A ma fallisca al commit H. Git bisect ha bisogno di due punti di riferimento: un commit buono, in cui la funzionalità funzionava sicuramente, e un commit difettoso, in cui il bug esiste sicuramente.
Estrae una revisione intermedia. Tu la testi, riferisci se funziona e Git riduce l'intervallo di ricerca rimanente. Per circa 128 commit candidati, la ricerca binaria richiede in genere circa sette test invece di esaminare tutti i 128, supponendo che il comportamento possa essere classificato in modo coerente.
La documentazione ufficiale di Git descrive il processo e i suoi limiti.
2. Crea una regressione PHP riproducibile
Costruiremo una minuscola funzione di calcolo del prezzo. Non sono necessari framework, database, pacchetti Composer o server web. Hai bisogno che Git e PHP CLI siano installati, e Git deve avere il tuo nome e la tua email dell'autore configurati per i commit.
Crea una directory e inizializza un repository:
mkdir git-bisect-demo
cd git-bisect-demo
git init
Crea price.php:
<?php
declare(strict_types=1);
function finalPrice(int $price, int $discount): int
{
return $price - $discount;
}
Il comportamento previsto è semplice: finalPrice(100, 20) restituisce 80.
Esegui il commit di questa versione funzionante:
git add price.php
git commit -m "Add working price calculation"
Successivamente, crea una modifica non correlata:
echo "# Price Calculator" > README.md
git add README.md
git commit -m "Add project documentation"
Infine, introduci un bug modificando il calcolo in price.php:
<?php
declare(strict_types=1);
function finalPrice(int $price, int $discount): int
{
return $price + $discount;
}
Esegui il commit della versione difettosa:
git add price.php
git commit -m "Refactor price calculation"
Il progetto ora ha tre commit, con una regressione deliberata nell'ultimo.
3. Trova la regressione manualmente
Inizia confermando che il tuo albero di lavoro è pulito:
git status --short
Il comando non dovrebbe produrre alcun output. Se hai modifiche non sottoposte a commit, eseguine il commit in modo appropriato o mettile da parte (stash) prima di iniziare.
Ora avvia Git bisect:
git bisect start
git bisect bad HEAD
git bisect good HEAD~2

Qui, HEAD è la revisione difettosa, mentre HEAD~2 punta al primo commit, quello funzionante. Git estrae il commit intermedio.
Testa il calcolo:
php -r 'require "price.php"; echo finalPrice(100, 20), PHP_EOL;'
Se l'output è 80, contrassegna la revisione come buona:
git bisect good
Se è 120, contrassegnala come difettosa:
git bisect bad
Git continua a selezionare commit finché non identifica la prima revisione difettosa. In questa dimostrazione con tre commit, è necessario testare una sola revisione intermedia.
Al termine, ripristina il tuo branch originale:
git bisect reset
Durante il bisect, Git normalmente estrae le revisioni storiche in uno stato di HEAD separato (detached HEAD). git bisect reset ti riporta alla revisione che stavi usando prima dell'indagine.
4. Automatizza l'indagine con git bisect run
Il test manuale è utile quando un bug richiede un'ispezione visiva. Ma se il comportamento può essere verificato da un comando, l'automazione è più efficiente.
Git supporta git bisect run <command>. Il comando comunica il proprio risultato tramite un codice di uscita:
| Codice di uscita | Significato |
|---|---|
0 |
Revisione buona |
1–124 o 126–127 |
Revisione difettosa |
125 |
Impossibile testare questa revisione |
| Altri valori | Interrompi l'indagine |
Queste regole provengono dal manuale ufficiale di Git bisect.
Crea uno script di test esterno al repository, come ../check-price.php:
<?php
declare(strict_types=1);
require __DIR__ . '/git-bisect-demo/price.php';
exit(finalPrice(100, 20) === 80 ? 0 : 1);
Lo script presuppone che la cartella del progetto si chiami git-bisect-demo e sia accanto a check-price.php. Esegui questi comandi dall'interno della cartella del progetto:
git bisect start HEAD HEAD~2
git bisect run php ../check-price.php
git bisect reset
Git esegue il test sulle revisioni storiche selezionate finché non viene identificato il primo commit difettoso. Poiché lo script di test è esterno al repository, l'estrazione di una revisione più vecchia non lo rimuove.
Per i progetti reali, usa un comando di test stabile o uno script di test esterno che funzioni con le revisioni storiche in esame.
5. Applica la tecnica a un progetto web reale
Lo stesso flusso di lavoro funziona per un plugin WordPress, un'estensione Joomla, un'applicazione JavaScript o una libreria PHP.
Supponi che una funzionalità di checkout sia rotta nell'ultima versione, ma che funzionasse nella release v1.4.0. Prima verifica che la release sia effettivamente buona, poi inizia:
git bisect start HEAD v1.4.0
Se il progetto ha un test PHPUnit che funziona attraverso le revisioni selezionate, puoi eseguirlo manualmente:
vendor/bin/phpunit tests/CheckoutTest.php
Dopo ogni test, riferisci git bisect good o git bisect bad.
Quando il test è automatizzato in modo affidabile:
git bisect run vendor/bin/phpunit tests/CheckoutTest.php
git bisect reset
I commit storici potrebbero richiedere diverse versioni di PHP, dipendenze, schemi di database o strumenti di build. Un test che fallisce perché l'ambiente è incompatibile non indica necessariamente la regressione. Assicurati che il tuo ambiente di test sia in grado di riprodurre le versioni storiche pertinenti.

6. Cosa succede se un vecchio commit non può essere testato?
A volte una revisione storica non riesce a compilare per un motivo non correlato. Non contrassegnarla automaticamente come difettosa.
Usa:
git bisect skip
Git prova un altro candidato. Per i test automatizzati, il codice di uscita 125 indica a Git di saltare la revisione.
Saltare troppi commit riduce la precisione. Se un commit non testabile è adiacente alla regressione, Git potrebbe segnalare più possibili responsabili invece di un unico commit esatto.
Una buona pratica a lungo termine è mantenere ambienti di sviluppo riproducibili, bloccare le versioni delle dipendenze e mantenere i test di regressione critici indipendenti dall'infrastruttura non correlata.
7. Ispeziona il commit che ha introdotto il bug
Una volta che Git ha identificato il primo commit difettoso, esaminalo:
git show <commit-hash>
Per vedere quali file sono stati modificati:
git show --stat <commit-hash>
Per ispezionare un file specifico:
git show <commit-hash> -- price.php
Il primo commit difettoso non è necessariamente l'unica causa del bug. Un commit potrebbe esporre un problema precedentemente nascosto, interagire con un'altra modifica o dipendere da un servizio esterno che è cambiato nel frattempo.
Usa il commit identificato per indagare la causa principale, non come prova automatica che ogni riga in quel commit sia errata.
8. Problemi comuni e soluzioni
Il bug compare in modo incoerente
Se un test a volte passa e a volte fallisce sulla stessa revisione, i risultati del bisect diventano inaffidabili. Esegui il test più volte, rimuovi le dipendenze temporali dove possibile e controlla gli input esterni. I test ripetuti migliorano l'affidabilità ma aumentano il tempo dell'indagine.
Il test fallisce su ogni revisione storica
Conferma che il tuo commit noto come funzionante sia davvero buono. Estrai quella revisione separatamente ed esegui il test prima di iniziare una nuova sessione di bisect. Se fallisce anche lì, il tuo test o il tuo ambiente potrebbero essere errati.
Git si rifiuta di cambiare revisione
Le modifiche non sottoposte a commit possono impedire l'estrazione. Controlla git status e preserva le tue modifiche prima di riavviare. Evita comandi distruttivi come git reset --hard a meno che tu non capisca esattamente cosa eliminano.
La cronologia contiene molti commit di merge
Per i repository complessi, Git supporta:
git bisect start --first-parent HEAD v1.4.0
Questo segue la cronologia first-parent e può aiutare a indagare le regressioni introdotte tramite i merge. Cambia quali commit vengono considerati, quindi non è un sostituto universale per un normale bisect.
Il bug dipende dai dati di produzione
Non eseguire mai il codice dell'applicazione storica su un database di produzione attivo. Usa un ambiente di test isolato con fixture ripulite e uno schema riproducibile. Le revisioni più vecchie potrebbero contenere migrazioni o assunzioni incompatibili con la produzione.
9. Una checklist pratica per il debug
- Conferma che il bug è riproducibile.
- Identifica una revisione nota per funzionare e una nota per fallire.
- Preserva le modifiche non sottoposte a commit.
- Definisci un test affidabile con un chiaro risultato positivo/negativo.
- Mantieni coerenti i servizi esterni e i dati di test.
- Usa
git bisect skipper le revisioni genuinamente non testabili. - Ispeziona il commit identificato e verifica la causa principale.
- Concludi con
git bisect reset.
Conclusione
Git bisect trasforma un compito di debug incerto in un'indagine strutturata. Invece di indovinare quale recente modifica abbia rotto un'applicazione, identifichi una revisione funzionante, una revisione difettosa e lasci che Git restringa la cronologia.
La tecnica diventa particolarmente potente se combinata con test automatizzati. Una regressione nascosta tra centinaia di commit può spesso essere localizzata con solo una manciata di verifiche.
Per gli sviluppatori che mantengono progetti PHP di lunga durata, plugin WordPress, estensioni Joomla o applicazioni JavaScript, git bisect è uno dei comandi Git più utili al di là del normale branching e merging quotidiano.