Web y desarrollo

Git Bisect: Encuentra el Commit que Introdujo un Bug

Git Bisect: Find the Commit That Introduced a Bug

Una característica funcionó ayer pero falla hoy. Aprende a usar Git bisect para identificar el commit que introdujo una regresión, probar revisiones automáticamente y investigar el resultado de forma segura.

Git Bisect: Encuentra el commit que introdujo un error

Un sitio web funcionó la semana pasada. Hoy, un cálculo de pago es incorrecto, un componente JavaScript ya no responde, o un endpoint de PHP devuelve datos inesperados.

Sabes que el error apareció en algún punto del historial de Git, pero el repositorio contiene decenas o cientos de commits desde la última versión funcional. Abrir cada commit y leer cada diff rara vez es la solución más rápida.

Git incluye una herramienta diseñada exactamente para esta situación: git bisect. En lugar de examinar cada commit, utiliza una búsqueda binaria para identificar la revisión que introdujo el problema por primera vez. Con una prueba confiable, puedes automatizar la investigación.

En este tutorial, crearás un pequeño proyecto PHP, introducirás deliberadamente una regresión, la localizarás con Git bisect y aprenderás a aplicar la misma técnica a proyectos reales.

1. Cómo funciona Git bisect

Imagina que tu aplicación funcionaba en el commit A pero falla en el commit H. Git bisect necesita dos puntos de referencia: un commit bueno, donde la función definitivamente funcionaba, y un commit malo, donde el error definitivamente existe.

Extrae una revisión intermedia. La pruebas, informas si funciona y Git reduce el rango de búsqueda restante. Para aproximadamente 128 commits candidatos, la búsqueda binaria generalmente requiere alrededor de siete pruebas en lugar de inspeccionar todos los 128, asumiendo que el comportamiento se pueda clasificar de manera consistente.

La documentación oficial de Git describe el proceso y sus limitaciones.

2. Crear una regresión PHP reproducible

Crearemos una pequeña función de cálculo de precios. No se requiere ningún framework, base de datos, paquete de Composer o servidor web. Necesitas Git y PHP CLI instalados, y Git debe tener tu nombre y correo de autor configurados para los commits.

Crea un directorio e inicializa un repositorio:

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;
}

El comportamiento esperado es sencillo: finalPrice(100, 20) devuelve 80.

Confirma esta versión funcional:

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

A continuación, crea un cambio no relacionado:

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

Por último, introduce un error cambiando el cálculo en price.php:

<?php

declare(strict_types=1);

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

Confirma la versión con error:

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

El proyecto ahora tiene tres commits, con una regresión deliberada en el último.

3. Encontrar la regresión manualmente

Comienza por confirmar que tu árbol de trabajo está limpio:

git status --short

El comando no debe producir salida. Si tienes trabajo sin confirmar, confírmalo adecuadamente o guárdalo en el stash antes de comenzar.

Ahora inicia Git bisect:

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

Aquí, HEAD es la revisión con error, mientras que HEAD~2 apunta al primer commit funcional. Git extrae el commit intermedio.

Prueba el cálculo:

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

Si la salida es 80, marca la revisión como buena:

git bisect good

Si es 120, márquela como mala:

git bisect bad

Git continúa seleccionando commits hasta identificar la primera revisión mala. En esta demostración de tres commits, solo se necesita probar una revisión intermedia.

Cuando termines, restaura tu rama original:

git bisect reset

Durante el bisect, Git normalmente extrae revisiones históricas en un estado HEAD desconectado. git bisect reset te devuelve a la revisión que estabas usando antes de la investigación.

4. Automatizar la investigación con git bisect run

La prueba manual es útil cuando un error requiere inspección visual. Pero si el comportamiento se puede verificar con un comando, la automatización es más eficiente.

Git admite git bisect run <command>. El comando comunica su resultado utilizando un código de salida:

Código de salida Significado
0 Revisión buena
1–124 o 126–127 Revisión mala
125 No se puede probar esta revisión
Otros valores Abortar la investigación

Estas reglas provienen del manual oficial de Git bisect.

Crea un script de prueba fuera del repositorio, como ../check-price.php:

<?php

declare(strict_types=1);

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

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

El script asume que la carpeta del proyecto se llama git-bisect-demo y está al lado de check-price.php. Ejecuta estos comandos desde dentro de la carpeta del proyecto:

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

Git ejecuta la prueba en las revisiones históricas seleccionadas hasta identificar el primer commit malo. Como el script de prueba está fuera del repositorio, extraer una revisión anterior no lo elimina.

Para proyectos reales, usa un comando de prueba estable o un script de prueba externo que funcione con las revisiones históricas bajo investigación.

5. Aplicar la técnica a un proyecto web real

El mismo flujo de trabajo funciona para un plugin de WordPress, una extensión de Joomla, una aplicación JavaScript o una librería PHP.

Supón que una función de pago está rota en la última versión, pero funcionaba en la versión v1.4.0. Primero verifica que la versión sea realmente buena, luego inicia:

git bisect start HEAD v1.4.0

Si el proyecto tiene una prueba de PHPUnit que funcione en las revisiones seleccionadas, puedes ejecutarla manualmente:

vendor/bin/phpunit tests/CheckoutTest.php

Después de cada prueba, informa git bisect good o git bisect bad.

Cuando la prueba esté automatizada de manera confiable:

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

Los commits históricos pueden requerir diferentes versiones de PHP, dependencias, esquemas de base de datos o herramientas de compilación. Una prueba que falle porque el entorno es incompatible no indica necesariamente la regresión. Asegúrate de que tu entorno de prueba pueda reproducir las versiones históricas relevantes.

Technical workflow illustration

6. ¿Qué sucede si un commit antiguo no se puede probar?

A veces, una revisión histórica no se compila por una razón no relacionada. No la marques automáticamente como mala.

Usa:

git bisect skip

Git intenta otro candidato. Para pruebas automatizadas, el código de salida 125 le indica a Git que omita la revisión.

Omitir demasiados commits reduce la precisión. Si un commit no probatable está adyacente a la regresión, Git puede informar múltiples posibles culpables en lugar de un commit exacto.

Una buena práctica a largo plazo es mantener entornos de desarrollo reproducibles, bloquear las versiones de las dependencias y mantener las pruebas de regresión críticas independientes de la infraestructura no relacionada.

7. Inspeccionar el commit que introdujo el error

Una vez que Git identifica el primer commit malo, examínalo:

git show <commit-hash>

Para ver qué archivos cambiaron:

git show --stat <commit-hash>

Para inspeccionar un archivo específico:

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

El primer commit malo no es necesariamente la única causa del error. Un commit podría exponer un problema previamente oculto, interactuar con otro cambio o depender de un servicio externo que ha cambiado desde entonces.

Usa el commit identificado para investigar la causa raíz, no como prueba automática de que cada línea en ese commit es incorrecta.

8. Problemas comunes y soluciones

El error aparece de manera inconsistente

Si una prueba a veces pasa y a veces falla en la misma revisión, los resultados de bisect se vuelven poco confiables. Ejecuta la prueba varias veces, elimina las dependencias de tiempo cuando sea posible y controla las entradas externas. Las pruebas repetidas mejoran la confianza, pero aumentan el tiempo de investigación.

La prueba falla en todas las revisiones históricas

Confirma que tu commit bueno conocido realmente sea bueno. Extrae esa revisión por separado y ejecuta la prueba antes de iniciar una nueva sesión de bisect. Si también falla allí, tu prueba o entorno puede ser incorrecto.

Git se niega a cambiar de revisión

Los cambios sin confirmar pueden impedir el checkout. Verifica git status y conserva tus cambios antes de reiniciar. Evita comandos destructivos como git reset --hard a menos que entiendas exactamente qué descartan.

El historial contiene muchos commits de fusión

Para repositorios complejos, Git admite:

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

Esto sigue el historial de primer padre y puede ayudar a investigar regresiones introducidas a través de fusiones. Cambia qué commits se consideran, por lo que no es un reemplazo universal para un bisect normal.

El error depende de datos de producción

Nunca ejecutes código de aplicación histórico contra una base de datos de producción en vivo. Usa un entorno de prueba aislado con datos de prueba desinfectados y un esquema reproducible. Las revisiones anteriores pueden contener migraciones o suposiciones incompatibles con la producción.

9. Una lista de verificación práctica para depuración

  • Confirma que el error es reproducible.
  • Identifica una revisión que se sepa que funciona y una que se sepa que falla.
  • Conserva el trabajo sin confirmar.
  • Define una prueba confiable con un resultado claro de aprobación o rechazo.
  • Mantén consistentes los servicios externos y los datos de prueba.
  • Usa git bisect skip para revisiones genuinamente no comprobables.
  • Inspecciona el commit identificado y verifica la causa raíz.
  • Finaliza con git bisect reset.

Conclusión

Git bisect convierte una tarea de depuración incierta en una investigación estructurada. En lugar de adivinar qué cambio reciente rompió una aplicación, identificas una revisión que funciona, una revisión rota, y dejas que Git reduzca el historial.

La técnica se vuelve especialmente poderosa cuando se combina con pruebas automatizadas. Una regresión oculta entre cientos de commits a menudo se puede localizar con solo unas pocas comprobaciones.

Para los desarrolladores que mantienen proyectos PHP de larga duración, plugins de WordPress, extensiones de Joomla o aplicaciones JavaScript, git bisect es uno de los comandos de Git más útiles más allá de la ramificación y fusión cotidianas.