git bisseção Encontrar o commit que causou o problema sem ler 500 linhas de log

Você fez 50 commits em duas semanas. Em algum momento, algo quebrou. O teste que passava há três semanas agora falha. git log --oneline mostra 200 linhas que você não quer ler.

Você tem opções: olhar para as diferenças até que seus olhos sangrem, git checkout fazer commits aleatórios e testar manualmente, ou usar a ferramenta que está no git desde 2007 e que vem com todas as instalações.

git bisect realiza uma busca binária no histórico de commits. Você marca um commit como quebrado e outro como funcionando, e ele verifica os commits entre eles — reduzindo o espaço de busca pela metade a cada vez. Encontrar o culpado em 500 commits leva cerca de 9 etapas. A maioria dos desenvolvedores nunca o usa.

Como funciona

O fluxo completo começa com três comandos:

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

O Git verifica um commit no meio entre esses dois pontos. Você testa se o erro existe e depois informa de volta:

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

O Git reduz o intervalo e escolhe o próximo ponto médio. Repita até que ele diga abc1234 is the first bad commit. Quando terminar:

git bisect reset  # returns you to your original branch

Sem flags especiais, sem configuração, sem plugins. Funciona em qualquer repositório, em qualquer versão do git que você provavelmente tenha instalado.

Uma sessão real de bisseção (anotada)

Aqui está uma sessão completa. Uma função que retornava JSON correto começou a retornar nulo após algumas recentes refatorações — sem culpado óbvio nos commits recentes:

$ 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 etapas em um intervalo de 50 commits. O commit "consolida manipuladores de resposta" havia removido silenciosamente uma chamada de serialização que algo no final da cadeia dependia. Sem bisseção, você teria lido diffs por uma hora.

Automatizando isso

Se você puder expressar a verificação como um script — sai com código 0 para bom, não-zero para ruim — o git bisect pode rodar totalmente sem intervenção humana:

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

O Git verifica cada ponto médio, executa o script e informa o primeiro commit defeituoso. Para testes que duram menos de 10 segundos, isso é rápido o suficiente para você sair e voltar com a resposta.

Sintaxe de códigos de saída para o script de execução:

• 0 — commit é bom
• 1–124 — commit é ruim
• 125 — pule este commit (build quebrado, não pode testar)

Use o 125 quando um commit não compila ou a infraestrutura de testes está quebrada nesse ponto — o bisect o pula e passa para o próximo candidato.

Quando o Bisect supera o git blame

git blame diz quem ultimamente tocou em uma linha. Útil quando você já sabe qual linha está errada. git bisect é para quando você não sabe — quando o sintoma é comportamental e a causa pode estar em qualquer lugar.

Use o bisseção quando:

• Você consegue reproduzir a regressão, mas não consegue rastrear para um arquivo específico
• O comportamento na produção mudou, mas não há suspeito óbvio na história recente
• "Isso funcionava na versão 2.3, quebrou na versão 2.5" com 80+ commits entre eles
• Um teste começou a falhar consistentemente em torno de uma data específica

Quando comparar a saída entre dois commits durante o bisseção, colar ambos em um ferramenta de diferença de texto é muitas vezes mais rápido do que ler diferenças unificadas no terminal — especialmente quando a saída é um bloco de JSON ou um objeto serializado.

Erros Comuns

Não esqueça git bisect reset. O bisseção verifica commits em estado HEAD desconectado. Se você mudar de ramo durante a sessão sem resetar, o estado do bisseção ficará obsoleto e você ficará confuso. Sempre resete quando terminar, mesmo após encontrar a resposta.

Commit de fusão pode distorcer o intervalo. Se seu intervalo incluir uma ramificação de recurso longa que foi mesclada, o bisseção pode cair dentro dos commits dessa ramificação em uma ordem não óbvia. Execute git log --oneline --no-merges good..bad primeiro para entender o que está no intervalo.

A reproduzibilidade do teste é tudo. Se seu teste for instável — sensível ao tempo, dependente do ambiente ou atingindo um serviço externo — o bisseção dará resultados ruins. Certifique-se de que o teste seja determinístico antes de automatizá-lo.

O commit identificado pelo bisseção é onde o comportamento mudou, não necessariamente onde o bug reside. Às vezes, uma refatoração correta expôs uma suposição pré-existente em outro lugar. Trate o resultado como "comece a ler aqui", não como "reverta isso e você está pronto".

Se você debuga regularmente o histórico do git, a Folha de dicas do Git na página IO Tools tem bisseção, blame, log e reflog tudo em uma página — vale a pena bookmarkar para a próxima vez que algo estranho quebrar.

Você também pode gostar