git bisect Trouver le commit qui a causé le problème sans lire 500 lignes de logs

Vous avez poussé 50 commits sur deux semaines. Partout dedans, quelque chose a cassé. Le test qui passait il y a trois semaines échoue maintenant. git log --oneline affiche 200 lignes que vous n'avez pas envie de lire.

Vous avez plusieurs options : regarder les diffs jusqu'à ce que vos yeux sanglent, git checkout faire des commits aléatoires et tester manuellement, ou utiliser l'outil qui existe depuis 2007 et qui est inclus avec chaque installation de git.

git bisect effectue une recherche binaire dans votre historique de commits. Vous marquez un commit comme cassé, un comme fonctionnel, et il sort les commits entre les deux — réduisant ainsi la plage de recherche à moitié chaque fois. Trouver le coupable parmi 500 commits prend environ 9 étapes. La plupart des développeurs ne l'utilisent jamais.

Comment ça marche

L'ensemble du workflow commence par trois commandes :

git bisect start
git bisect bad                 # current state is broken
git bisect good v2.4.0         # last known-good tag or commit hash

Git sort un commit à mi-chemin entre ces deux points. Vous testez la présence du bug, puis vous retournez le résultat :

git bisect good   # bug is NOT present here
# or
git bisect bad    # bug IS present here

Git réduit la plage et choisit le nouveau point milieu. Répétez jusqu'à ce qu'il vous dise abc1234 is the first bad commit. Quand vous êtes terminé :

git bisect reset  # returns you to your original branch

Aucune option spéciale, aucune configuration, aucun plugin. Fonctionne sur tout dépôt, sur toute version de git que vous avez probablement installée.

Séance réelle de bisect (annotée)

Voici une session complète. Une fonction qui renvoyait correctement du JSON a commencé à renvoyer null après quelques réfactos récents — aucun coupable évident dans les commits récents :

$ git bisect start
$ git bisect bad HEAD              # current commit is broken
$ git bisect good 3f8a12b          # commit from 2 weeks ago, worked fine

Bisecting: 24 revisions left to test after this (roughly 5 steps)
[c9e41f0] Refactor: extract auth middleware

$ npm test -- --grep "parseResponse"   # ← run your check here
# FAIL
$ git bisect bad

Bisecting: 12 revisions left to test after this (roughly 4 steps)
[a77b2d1] Fix: update retry logic in fetch wrapper

$ npm test -- --grep "parseResponse"
# PASS
$ git bisect good

Bisecting: 6 revisions left to test after this (roughly 3 steps)
[91e0bc3] Refactor: consolidate response handlers

$ npm test -- --grep "parseResponse"
# FAIL
$ git bisect bad

Bisecting: 2 revisions left to test after this (roughly 2 steps)
[b44c19f] Chore: remove deprecated serialization helpers

$ npm test -- --grep "parseResponse"
# FAIL
$ git bisect bad

Bisecting: 1 revision left to test after this (roughly 1 step)
[8d3e77a] Fix: normalize response envelope for new API version

$ npm test -- --grep "parseResponse"
# PASS
$ git bisect good

91e0bc3e1f4d is the first bad commit
commit 91e0bc3e1f4d
Author: Dev <dev@example.com>
Date:   Mon Apr 14 11:23:07 2026

    Refactor: consolidate response handlers

 src/http/response.js | 14 +++---

$ git bisect reset   # ← always do this when done

5 étapes sur une plage de 50 commits. Le commit « consolider les gestionnaires de réponse » avait silencieusement supprimé une appelle de sérialisation que quelque chose de downstream dépendait. Sans bisect, vous auriez lu des diffs pendant une heure.

Automatisation

Si vous pouvez exprimer le test sous forme de script — sortie 0 pour un bon résultat, code non nul pour un mauvais résultat — git bisect peut fonctionner entièrement sans intervention humaine :

git bisect start
git bisect bad HEAD
git bisect good v2.4.0
git bisect run npm test -- --grep "parseResponse"

Git sort chaque point milieu, exécute le script et indique le premier commit défectueux. Pour des tests qui durent moins de 10 secondes, cela est rapide assez pour vous éloigner et revenir avec la réponse.

Sémantique des codes de sortie pour le script d'exécution :

• 0 — commit est bon
• 1–124 — commit est mauvais
• 125 — sauter ce commit (build cassé, impossible de le tester)

Utilisez 125 quand un commit ne compile pas ou que l'infrastructure de test est cassée à ce point — bisect le saute et passe au candidat suivant.

Quand bisect dépasse git blame

git blame vous indique qui a dernierement modifié une ligne. Utile quand vous savez déjà quelle ligne est erronée. git bisect est utilisé quand vous ne le savez pas — quand le symptôme est comportemental et que la cause pourrait être n'importe où.

Utilisez bisect quand :

• Vous pouvez reproduire la régression mais ne pouvez pas la suivre à un fichier spécifique
• Le comportement en production a changé mais aucun suspect évident dans l'histoire récente
• « Cela fonctionnait en v2.3, cassé en v2.5 » avec 80+ commits entre les deux versions
• Un test a commencé à échouer de manière constante autour d'une date donnée

Lors de la comparaison des sorties entre deux commits pendant le bisect, coller les deux dans un outil de diff de texte est souvent plus rapide que la lecture des diffs unifiés dans le terminal — surtout quand le résultat est un bloc de JSON ou un objet sérialisé.

Pièges courants

N'oubliez pas git bisect reset. Bisect sort les commits en état de HEAD détaché. Si vous passez en branche au milieu de la session sans réinitialiser, l'état de bisect sera obsolète et vous serez confus. Réinitialisez toujours à la fin, même après avoir trouvé la réponse.

Les commits de fusion peuvent distordre la plage. Si votre plage inclut une branche de fonctionnalité longue durée qui a été fusionnée, bisect pourrait se placer dans les commits de cette branche dans un ordre non évident. Exécutez d'abord git log --oneline --no-merges good..bad pour comprendre ce qui se trouve dans la plage.

La réproductibilité du test est tout. Si votre test est instable — sensible au temps, dépendant de l'environnement ou touchant un service externe — bisect vous donnera des résultats incorrects. Assurez-vous que le test est déterministe avant de l'automatiser.

Le commit identifié par bisect est le point où le comportement a changé, pas nécessairement le point où réside le bug. Parfois, un refactor correct a révélé une hypothèse préexistante ailleurs. Traitez le résultat comme « commencez à lire ici », et non pas « revenez à ce commit et vous êtes finis ».

Si vous déboguez régulièrement l'historique de git, la Aide-mémoire Git sur IO Tools dispose de bisect, blame, log et reflog tous sur une même page — mérite d'être bookmarké pour la prochaine fois où quelque chose brise mystérieusement.

Vous aimerez peut-être aussi