Web e Desenvolvimento

Git Bisect: Encontre o Commit que Introduziu um Bug

Git Bisect: Find the Commit That Introduced a Bug

Um recurso funcionava ontem, mas falha hoje. Aprenda a usar o Git bisect para localizar o commit que introduziu uma regressão, testar revisões automaticamente e investigar o resultado com segurança.

Um site funcionava na semana passada. Hoje, um cálculo de checkout está errado, um componente JavaScript não responde mais ou um endpoint PHP retorna dados inesperados.

Você sabe que o bug apareceu em algum lugar no histórico do Git, mas o repositório contém dezenas ou centenas de commits desde a última versão que funcionava. Abrir cada commit e ler cada diff raramente é a solução mais rápida.

O Git inclui uma ferramenta criada para exatamente essa situação: git bisect. Em vez de examinar cada commit, ele usa uma busca binária para identificar a revisão que primeiro introduziu o problema. Com um teste confiável, você pode automatizar a investigação.

Neste tutorial, você criará um pequeno projeto PHP, introduzirá deliberadamente uma regressão, localizará ela com o Git bisect e aprenderá como aplicar a mesma técnica a projetos reais.

1. Como o Git bisect funciona

Imagine que sua aplicação funcionava no commit A, mas falha no commit H. O Git bisect precisa de dois pontos de referência: um commit bom, onde a funcionalidade definitivamente funcionava, e um commit ruim, onde o bug definitivamente existe.

Ele faz checkout de uma revisão intermediária. Você testa, informa se funciona, e o Git reduz o intervalo de busca restante. Para aproximadamente 128 commits candidatos, a busca binária normalmente requer cerca de sete testes, em vez de inspecionar os 128, assumindo que o comportamento possa ser classificado consistentemente.

A documentação oficial do Git descreve o processo e suas limitações.

2. Crie uma regressão PHP reproduzível

Construiremos uma pequena função de cálculo de preço. Não é necessário framework, banco de dados, pacote Composer ou servidor web. Você precisa ter o Git e o PHP CLI instalados, e o Git deve ter seu nome de autor e e-mail configurados para os commits.

Crie um diretório e inicialize um repositório:

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

Crie price.php:

<?php

declare(strict_types=1);

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

O comportamento esperado é simples: finalPrice(100, 20) retorna 80.

Faça o commit desta versão funcionando:

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

Em seguida, crie uma alteração não relacionada:

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

Finalmente, introduza um bug alterando o cálculo em price.php:

<?php

declare(strict_types=1);

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

Faça o commit da versão quebrada:

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

O projeto agora tem três commits, com uma regressão deliberada no último.

3. Encontre a regressão manualmente

Comece confirmando que sua árvore de trabalho está limpa:

git status --short

O comando não deve produzir saída. Se você tem trabalho não commitado, faça o commit adequadamente ou stash antes de começar.

Agora inicie o Git bisect:

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

Aqui, HEAD é a revisão quebrada, enquanto HEAD~2 aponta para o primeiro commit funcionando. O Git faz checkout da revisão intermediária.

Teste o cálculo:

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

Se a saída for 80, marque a revisão como boa:

git bisect good

Se for 120, marque-a como ruim:

git bisect bad

O Git continua selecionando commits até identificar a primeira revisão ruim. Nesta demonstração de três commits, apenas uma revisão intermediária precisa ser testada.

Quando terminar, restaure seu branch original:

git bisect reset

Durante o bisect, o Git normalmente faz checkout de revisões históricas em um estado detached HEAD. git bisect reset retorna você à revisão que você estava usando antes da investigação.

4. Automatize a investigação com git bisect run

Um teste manual é útil quando um bug requer inspeção visual. Mas se o comportamento puder ser verificado por um comando, a automação é mais eficiente.

O Git suporta git bisect run <command>. O comando comunica seu resultado usando um código de saída:

Código de saída Significado
0 Revisão boa
1–124 ou 126–127 Revisão ruim
125 Não é possível testar esta revisão
Outros valores Abortar a investigação

Essas regras vêm do manual oficial do Git bisect.

Crie um script de teste fora do repositório, como ../check-price.php:

<?php

declare(strict_types=1);

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

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

O script assume que a pasta do projeto se chama git-bisect-demo e está ao lado de check-price.php. Execute estes comandos a partir da pasta do projeto:

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

O Git executa o teste nas revisões históricas selecionadas até que o primeiro commit ruim seja identificado. Como o script de teste está fora do repositório, fazer checkout de uma revisão mais antiga não o remove.

Para projetos reais, use um comando de teste estável ou um script de teste externo que funcione com as revisões históricas em investigação.

5. Aplique a técnica a um projeto web real

Este mesmo fluxo funciona para um plugin do WordPress, uma extensão do Joomla, um aplicativo JavaScript ou uma biblioteca PHP.

Suponha que um recurso de checkout esteja quebrado na versão mais recente, mas funcionasse no release v1.4.0. Primeiro, verifique se o release realmente é bom, depois comece:

git bisect start HEAD v1.4.0

Se o projeto tem um teste PHPUnit que funciona nas revisões selecionadas, você pode executá-lo manualmente:

vendor/bin/phpunit tests/CheckoutTest.php

Após cada teste, informe git bisect good ou git bisect bad.

Quando o teste for automaticamente confiável:

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

Commits históricos podem exigir versões diferentes do PHP, dependências, schemas de banco de dados ou ferramentas de build. Um teste que falha porque o ambiente é incompatível não indica necessariamente a regressão. Certifique-se de que seu ambiente de teste possa reproduzir as versões históricas relevantes.

Technical workflow illustration

6. O que fazer se um commit antigo não puder ser testado?

Às vezes, uma revisão histórica falha ao compilar por um motivo não relacionado. Não a marque automaticamente como ruim.

Use:

git bisect skip

O Git tenta outro candidato. Para testes automatizados, o código de saída 125 informa ao Git para pular a revisão.

Pular muitos commits reduz a precisão. Se um commit não testável for adjacente à regressão, o Git pode reportar vários possíveis culpados em vez de um único commit exato.

Uma boa prática a longo prazo é manter ambientes de desenvolvimento reproduzíveis, travar versões de dependências e manter testes de regressão críticos independentes de infraestrutura não relacionada.

7. Inspecione o commit que introduziu o bug

Quando o Git identificar o primeiro commit ruim, examine-o:

git show <commit-hash>

Para ver quais arquivos mudaram:

git show --stat <commit-hash>

Para inspecionar um arquivo específico:

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

O primeiro commit ruim não é necessariamente a única causa do bug. Um commit pode expor um problema anteriormente oculto, interagir com outra alteração ou depender de um serviço externo que mudou desde então.

Use o commit identificado para investigar a causa raiz, não como prova automática de que cada linha daquele commit está incorreta.

8. Problemas e soluções comuns

O bug aparece de forma inconsistente

Se um teste às vezes passa e às vezes falha na mesma revisão, os resultados do bisect se tornam não confiáveis. Execute o teste várias vezes, remova dependências de tempo quando possível e controle as entradas externas. Testes repetidos melhoram a confiança, mas aumentam o tempo de investigação.

O teste falha em todas as revisões históricas

Confirme que seu commit conhecido como bom realmente é bom. Faça checkout dessa revisão separadamente e execute o teste antes de iniciar uma nova sessão de bisect. Se falhar lá também, seu teste ou ambiente podem estar incorretos.

O Git se recusa a alternar revisões

Alterações não commitadas podem impedir o checkout. Verifique git status e preserve suas alterações antes de reiniciar. Evite comandos destrutivos como git reset --hard, a menos que você entenda exatamente o que eles descartam.

O histórico contém muitos commits de merge

Para repositórios complexos, o Git suporta:

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

Isso segue o histórico first-parent e pode ajudar a investigar regressões introduzidas por merges. Ele muda quais commits são considerados, então não é uma substituição universal para um bisect normal.

O bug depende de dados de produção

Nunca execute código de aplicação histórico contra um banco de dados de produção ativo. Use um ambiente de teste isolado com fixtures sanitizadas e um schema reproduzível. Revisões mais antigas podem conter migrações ou suposições incompatíveis com a produção.

9. Uma lista de verificação prática de depuração

  • Confirme que o bug é reproduzível.
  • Identifique uma revisão conhecida por funcionar e uma conhecida por falhar.
  • Preserve o trabalho não commitado.
  • Defina um teste confiável com um resultado claro de passar/falhar.
  • Mantenha serviços externos e dados de teste consistentes.
  • Use git bisect skip para revisões genuinamente intocáveis.
  • Inspecione o commit identificado e verifique a causa raiz.
  • Termine com git bisect reset.

Conclusão

O Git bisect transforma uma tarefa de depuração incerta em uma investigação estruturada. Em vez de adivinhar qual alteração recente quebrou um aplicativo, você identifica uma revisão funcionando, uma revisão quebrada e deixa o Git estreitar o histórico.

A técnica se torna especialmente poderosa quando combinada com testes automatizados. Uma regressão escondida entre centenas de commits pode muitas vezes ser localizada com apenas algumas verificações.

Para desenvolvedores que mantêm projetos PHP de longa duração, plugins do WordPress, extensões Joomla ou aplicativos JavaScript, git bisect é um dos comandos Git mais úteis além de branching e merging do dia a dia.