git bisect Encontrar el commit que causó el fallo sin leer 500 líneas de registro

Hiciste 50 commits en dos semanas. En algún momento, algo falló. Un test que pasaba hace tres semanas ahora falla. git log --oneline muestra 200 líneas que no quieres leer.

Tienes opciones: mirar diffs hasta que tus ojos sangren, git checkout hacer commits aleatorios y probarlos manualmente, o usar la herramienta que ha estado en git desde 2007 y que viene con cada instalación.

git bisect realiza una búsqueda binaria en tu historia de commits. Marcas un commit como fallido, otro como funcionando, y se revisan los commits intermedios — reduciendo el espacio de búsqueda a la mitad cada vez. Encontrar al culpable en 500 commits toma aproximadamente 9 pasos. La mayoría de los desarrolladores nunca la usan.

Cómo funciona

El flujo completo comienza con tres comandos:

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

Git saca un commit en el punto medio entre esos dos puntos. Pruebas si el fallo existe, y luego reportas:

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

Git reduce el rango y elige el siguiente punto medio. Repite hasta que te diga abc1234 is the first bad commit. Cuando termines:

git bisect reset  # returns you to your original branch

Sin flags especiales, sin configuración, sin plugins. Funciona en cualquier repositorio, en cualquier versión de git que probablemente tengas instalada.

Sesión real de bisect (anotada)

Aquí tienes una sesión completa. Una función que devolvía JSON correcto comenzó a devolver null tras algunas refactorizaciones recientes — sin culpable evidente en los commits recientes:

$ 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 pasos en un rango de 50 commits. El commit «consolidar gestores de respuesta» había eliminado silenciosamente una llamada de serialización que algo más abajo dependía. Sin bisect, habrías estado leyendo diffs durante una hora.

Automatización

Si puedes expresar la comprobación como un script — sale 0 si todo está bien, número diferente si hay un error — git bisect puede ejecutarse completamente sin intervención humana:

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

Git saca cada punto medio, ejecuta el script y reporta el primer commit malo. Para pruebas que duran menos de 10 segundos, esto es rápido enough para salir y regresar con la respuesta.

Sintaxis de códigos de salida para el script de ejecución:

• 0 — commit es bueno
• 1–124 — commit es malo
• 125 — saltar este commit (construcción fallida, no se puede probar)

Usa 125 cuando un commit no se compila o la infraestructura de pruebas está dañada en ese punto — bisect lo salta y avanza al siguiente candidato.

Cuando bisect supera a git blame

git blame te dice quién fue el último en tocar una línea. Útil cuando ya sabes que línea está mal. git bisect es cuando no lo sabes — cuando el síntoma es comportamental y la causa podría estar en cualquier lugar.

Usa bisect cuando:

• Puedes reproducir el regreso pero no puedes rastrearlo a un archivo específico
• El comportamiento en producción cambió, pero no hay sospecha obvia en la historia reciente
• «Funcionaba en v2.3, falló en v2.5» con 80+ commits entre ellos
• Un test comenzó a fallar de forma consistente alrededor de una fecha específica

Cuando al comparar el resultado entre dos commits durante el bisect, pegar ambos en un herramienta de diferencias de texto a menudo es más rápida que leer diferencias unificadas en la terminal — especialmente cuando el resultado es un bloque de JSON o un objeto serializado.

Trucos comunes para evitar errores

No olvides git bisect reset. Bisect saca commits en estado HEAD desconectado. Si cambias de rama durante la sesión sin restablecer, el estado de bisect será obsoleto y te confundirás. Siempre restablece cuando termines, incluso después de encontrar la solución.

Los commits de fusión pueden distorsionar el rango. Si tu rango incluye una rama de características que ha sido fusionada, bisect podría aterrizar dentro de los commits de esa rama en un orden no obvio. Ejecuta git log --oneline --no-merges good..bad primero para entender qué hay en el rango.

La reproducibilidad de la prueba es todo. Si tu comprobación es inestable — dependiente del tiempo, del entorno o de un servicio externo — bisect te dará resultados incorrectos. Asegúrate de que la prueba sea determinística antes de automatizarla.

El commit que identifica bisect es donde cambió el comportamiento, no necesariamente donde vive el fallo. A veces un refactor correcto reveló una suposición previa en otro lugar. Trata el resultado como «comienza a leer aquí», no como «revertir este y estás listo».

Si analizas regularmente el historial de git, la Hoja de trucos de Git en IO Tools tiene bisect, blame, log y reflog en una misma página — vale la pena bookmarkear para la próxima vez que algo misterioso falle.

También te puede interesar