Web et développement

Git Bisect : Trouver le commit qui a introduit un bug

Git Bisect: Find the Commit That Introduced a Bug

Une fonctionnalité fonctionnait hier mais échoue aujourd'hui. Apprenez à utiliser Git bisect pour localiser le commit qui a introduit une régression, tester les révisions automatiquement, et enquêter sur le résultat en toute sécurité.

Un site web fonctionnait la semaine dernière. Aujourd'hui, un calcul de checkout est incorrect, un composant JavaScript ne répond plus, ou un endpoint PHP renvoie des données inattendues.

Vous savez que le bug est apparu quelque part dans l'historique Git, mais le dépôt contient des dizaines ou des centaines de commits depuis la dernière version fonctionnelle. Ouvrir chaque commit et lire chaque diff est rarement la solution la plus rapide.

Git inclut un outil conçu exactement pour cette situation : git bisect. Au lieu d'examiner chaque commit, il utilise une recherche binaire pour identifier la révision qui a introduit le problème. Avec un test fiable, vous pouvez automatiser l'investigation.

Dans ce tutoriel, vous créerez un petit projet PHP, introduirez délibérément une régression, la localiserez avec Git bisect, et apprendrez à appliquer la même technique à de vrais projets.

1. Comment Git bisect fonctionne

Imaginez que votre application fonctionnait au commit A mais échoue au commit H. Git bisect a besoin de deux points de référence : un commit bon, où la fonctionnalité fonctionnait certainement, et un commit mauvais, où le bug existait certainement.

Il vérifie une révision intermédiaire. Vous la testez, rapportezz si elle fonctionne, et Git réduit la plage de recherche restante. Pour environ 128 commits candidats, la recherche binaire nécessite généralement environ sept tests au lieu d'inspecter les 128, en supposant que le comportement peut être classé de manière cohérente.

La documentation officielle de Git décrit le processus et ses limites.

2. Créer une régression PHP reproductible

Nous allons construire une petite fonction de calcul de prix. Aucun framework, base de données, package Composer ou serveur web n'est requis. Vous devez avoir Git et PHP CLI installés, et Git doit avoir votre nom d'auteur et votre e-mail configurés pour les commits.

Créez un répertoire et initialisez un dépôt :

mkdir git-bisect-demo
cd git-bisect-demo
git init

Créez price.php :

<?php

declare(strict_types=1);

function finalPrice(int $price, int $discount): int
{
    return $price - $discount;
}

Le comportement attendu est simple : finalPrice(100, 20) retourne 80.

Committez cette version fonctionnelle :

git add price.php
git commit -m "Add working price calculation"

Ensuite, créez un changement sans rapport :

echo "# Price Calculator" > README.md
git add README.md
git commit -m "Add project documentation"

Enfin, introduisez un bug en modifiant le calcul dans price.php :

<?php

declare(strict_types=1);

function finalPrice(int $price, int $discount): int
{
    return $price + $discount;
}

Committez la version cassée :

git add price.php
git commit -m "Refactor price calculation"

Le projet compte maintenant trois commits, avec une régression délibérée dans le dernier.

3. Trouver la régression manuellement

Commencez par confirmer que votre arborescence de travail est propre :

git status --short

La commande ne doit produire aucune sortie. Si vous avez des modifications non commitées, commitez-les correctement ou stachez-les avant de commencer.

Lançons maintenant Git bisect :

git bisect start
git bisect bad HEAD
git bisect good HEAD~2
Illustration of the article's main concept

Ici, HEAD est la révision cassée, tandis que HEAD~2 pointe vers le premier commit fonctionnel. Git vérifie le commit intermédiaire.

Testez le calcul :

php -r 'require "price.php"; echo finalPrice(100, 20), PHP_EOL;'

Si la sortie est 80, marquez la révision comme bonne :

git bisect good

Si c'est 120, marquez-la comme mauvaise :

git bisect bad

Git continue de sélectionner les commits jusqu'à identifier la première révision mauvaise. Dans cette démonstration à trois commits, une seule révision intermédiaire nécessite un test.

Quand c'est terminé, restaurez votre branche d'origine :

git bisect reset

Pendant le bisect, Git vérifie normalement les révisions historiques dans un état HEAD détaché. git bisect reset vous ramène à la révision que vous utilisiez avant l'investigation.

4. Automatiser l'investigation avec git bisect run

Les tests manuels sont utiles lorsqu'un bug nécessite une inspection visuelle. Mais si le comportement peut être vérifié par une commande, l'automatisation est plus efficace.

Git prend en charge git bisect run <command>. La commande communique son résultat via un code de sortie :

Code de sortie Signification
0 Bonne révision
1–124 ou 126–127 Mauvaise révision
125 Impossible de tester cette révision
Autres valeurs Abandonner l'investigation

Ces règles proviennent du manuel officiel de Git bisect.

Créez un script de test en dehors du dépôt, comme ../check-price.php :

<?php

declare(strict_types=1);

require __DIR__ . '/git-bisect-demo/price.php';

exit(finalPrice(100, 20) === 80 ? 0 : 1);

Le script suppose que le dossier du projet s'appelle git-bisect-demo et est situé à côté de check-price.php. Exécutez ces commandes depuis le dossier du projet :

git bisect start HEAD HEAD~2
git bisect run php ../check-price.php
git bisect reset

Git exécute le test sur les révisions historiques sélectionnées jusqu'à ce que le premier commit mauvais soit identifié. Parce que le script de test est en dehors du dépôt, la vérification d'une révision plus ancienne ne le supprime pas.

Pour de vrais projets, utilisez une commande de test stable ou un script de test externe qui fonctionne avec les révisions historiques sous investigation.

5. Appliquer la technique à un vrai projet web

Le même processus fonctionne pour un plugin WordPress, une extension Joomla, une application JavaScript ou une bibliothèque PHP.

Supposez qu'une fonctionnalité de checkout soit cassée dans la dernière version, mais qu'elle fonctionnait dans la version v1.4.0. Vérifiez d'abord que la version est réellement bonne, puis commencez :

git bisect start HEAD v1.4.0

Si le projet a un test PHPUnit qui fonctionne sur les révisions sélectionnées, vous pouvez l'exécuter manuellement :

vendor/bin/phpunit tests/CheckoutTest.php

Après chaque test, signalez git bisect good ou git bisect bad.

Quand le test est de manière fiable automatisé :

git bisect run vendor/bin/phpunit tests/CheckoutTest.php
git bisect reset

Les commits historiques peuvent nécessiter différentes versions de PHP, dépendances, schémas de base de données ou outils de build. Un test qui échoue parce que l'environnement est incompatible ne signifie pas nécessairement que c'est la régression. Assurez-vous que votre environnement de test peut reproduire les versions historiques pertinentes.

Technical workflow illustration

6. Que se passe-t-il si un ancien commit ne peut pas être testé ?

Parfois, une révision historique échoue à compiler pour une raison sans rapport. Ne la marquez pas automatiquement comme mauvaise.

Utilisez :

git bisect skip

Git essaie un autre candidat. Pour les tests automatisés, le code de sortie 125 indique à Git de sauter la révision.

Sauter trop de commits réduit la précision. Si un commit non testable est adjacent à la régression, Git peut signaler plusieurs coupables possibles plutôt qu'un seul commit exact.

Une bonne pratique à long terme est de maintenir des environnements de développement reproductibles, de verrouiller les versions des dépendances et de garder les tests de régression critiques indépendants de l'infrastructure non liée.

7. Inspecter le commit qui a introduit le bug

Une fois Git ayant identifié le premier commit mauvais, examinez-le :

git show <commit-hash>

Pour voir quels fichiers ont changé :

git show --stat <commit-hash>

Pour inspecter un fichier spécifique :

git show <commit-hash> -- price.php

Le premier commit mauvais n'est pas nécessairement la seule cause du bug. Un commit peut exposer un problème auparavant caché, interagir avec un autre changement ou dépendre d'un service externe qui a depuis changé.

Utilisez le commit identifié pour enquêter sur la cause racine, et non comme preuve automatique que chaque ligne de ce commit est incorrecte.

8. Problèmes courants et solutions

Le bug apparaît de manière incohérente

Si un test échoue parfois et passe parfois sur la même révision, les résultats du bisect deviennent peu fiables. Exécutez le test plusieurs fois, supprimez les dépendances de timing lorsque c'est possible, et contrôlez les entrées externes. Les tests répétés améliorent la confiance mais augmentent le temps d'investigation.

Le test échoue sur toutes les révisions historiques

Confirmez que votre commit connu bon est vraiment bon. Vérifiez cette révision séparément et exécutez le test avant de commencer une nouvelle session de bisect. Si elle échoue aussi, votre test ou votre environnement peut être incorrect.

Git refuse de changer de révision

Les modifications non commitées peuvent empêcher le checkout. Vérifiez git status et conservez vos modifications avant de redémarrer. Évitez les commandes destructives comme git reset --hard à moins de comprendre exactement ce qu'elles suppriment.

L'historique contient de nombreux commits de fusion

Pour les dépôts complexes, Git prend en charge :

git bisect start --first-parent HEAD v1.4.0

Ceci suit l'historique first-parent et peut aider à investiguer les régressions introduites par des fusions. Cela change les commits considérés, donc ce n'est pas un remplacement universel d'un bisect normal.

Le bug dépend de données de production

N'exécutez jamais le code applicatif historique contre une base de données de production en direct. Utilisez un environnement de test isolé avec des données de test nettoyées et un schéma reproductible. Les révisions plus anciennes peuvent contenir des migrations ou des hypothèses incompatibles avec la production.

9. Une liste de contrôle pratique pour le débogage

  • Confirmez que le bug est reproductible.
  • Identifiez une révision connue pour fonctionner et une connue pour échouer.
  • Conservez les modifications non commitées.
  • Définissez un test fiable avec un résultat clair de réussite/échec.
  • Gardez les services externes et les données de test cohérents.
  • Utilisez git bisect skip pour les révisions vraiment impossibles à tester.
  • Inspectez le commit identifié et vérifiez la cause racine.
  • Terminez avec git bisect reset.

Conclusion

Git bisect transforme une tâche de débogage incertaine en une investigation structurée. Au lieu de deviner quel changement récent a cassé une application, vous identifiez une révision fonctionnelle, une révision cassée, et laissez Git réduire l'historique.

La technique devient particulièrement puissante lorsqu'elle est combinée avec des tests automatisés. Une régression cachée parmi des centaines de commits peut souvent être localisée avec seulement quelques vérifications.

Pour les développeurs qui maintiennent des projets PHP de longue durée, des plugins WordPress, des extensions Joomla ou des applications JavaScript, git bisect est l'un des commandes Git les plus utiles au-delà du branching et du merging quotidiens.