Git Bisect: Znajdź commit, który wprowadził błąd
Funkcja działała wczoraj, ale dzisiaj nie działa. Dowiedz się, jak używać Git bisect, aby zidentyfikować commit, który wprowadził regresję, automatycznie testować zmiany i bezpiecznie analizować wynik.
Niedawno strona działała poprawnie, ale dziś mamy problem: błędne obliczenia podczas wycofywania transakcji, brak reakcji komponentu JavaScript lub nieoczekiwane dane zwracane przez punkt końcowy PHP.
Wiesz, że błąd pojawił się gdzieś w historii commity Git, ale repozytorium zawiera dziesiątki lub nawet setki commitów od czasu ostatniej poprawnej wersji. Otwieranie każdego commitu i analizowanie wszystkich diffów rzadko jest najszybszym rozwiązaniem.
Git zawiera narzędzie zaprojektowane właśnie na taką sytuację: git bisect. Zamiast badać każdy commit, używa wyszukiwania binarnego, aby zidentyfikować wersję, która po raz pierwszy wprowadziła problem. Dzięki niezawodnemu testowi możesz zautomatyzować proces dochodzenia.
W tym samouczku utworzysz mały projekt PHP, celowo wprowadzisz regresję, zlokalizujesz ją za pomocą Git bisect i nauczysz się stosować tę samą technikę w prawdziwych projektach.
1. Jak działa Git bisect
Wyobraź sobie, że twoja aplikacja działała w commicie A, ale nie działa w commicie H. Git bisect potrzebuje dwóch punktów odniesienia: dobrego commitu, w którym funkcja na pewno działała, i złego commitu, w którym błąd na pewno występuje.
Git sprawdza commity pośrednie. Testujesz je, zgłaszasz, czy działają, a Git zmniejsza pozostały zakres wyszukiwania. Dla około 128 kandydatów binary search zwykle wymaga około siedmiu testów zamiast inspekcji wszystkich 128, zakładając, że zachowanie można sklasyfikować w sposób spójny.
Oficjalna dokumentacja Git opisuje proces i jego ograniczenia.
2. Utwórz powtarzalną regresję w PHP
Stworzymy małą funkcję obliczania cen. Nie są potrzebne żadne frameworki, bazy danych, pakiety Composer ani serwer internetowy. Musisz mieć zainstalowany Git i PHP CLI, a Git musi mieć skonfigurowane Twoje nazwisko i adres e-mail dla commitów.
Utwórz katalog i zainicjuj repozytorium:
mkdir git-bisect-demo
cd git-bisect-demo
git init
Utwórz price.php:
<?php
declare(strict_types=1);
function finalPrice(int $price, int $discount): int
{
return $price - $discount;
}
Oczekiwane zachowanie jest proste: finalPrice(100, 20) zwraca 80.
Zatwierdź tę poprawne wersję:
git add price.php
git commit -m "Add working price calculation"
Następnie utwórz niepowiązaną zmianę:
echo "# Price Calculator" > README.md
git add README.md
git commit -m "Add project documentation"
Na koniec wprowadź błąd, zmieniając obliczenia w price.php:
<?php
declare(strict_types=1);
function finalPrice(int $price, int $discount): int
{
return $price + $discount;
}
Zatwierdź wersję z błędem:
git add price.php
git commit -m "Refactor price calculation"
Projekt ma teraz trzy commity, z celową regresją w ostatnim z nich.
3. Znajdź regresję ręcznie
Najpierw sprawdź, czy Twoja kopia robocza jest czysta:
git status --short
Polecenie nie powinno dać żadnego wyniku. Jeśli masz niezatwierdzone zmiany, zatwierdź je odpowiednio lub je przechowaj zanim zaczniesz.
Teraz uruchom Git bisect:
git bisect start
git bisect bad HEAD
git bisect good HEAD~2

Tutaj HEAD to zły commit, podczas gdy HEAD~2 wskazuje na pierwszy, dobry commit. Git sprawdza commity pośrednie.
Przetestuj obliczenia:
php -r 'require "price.php"; echo finalPrice(100, 20), PHP_EOL;'
Jeśli wynik to 80, oznacz ten commit jako dobry:
git bisect good
Jeśli jest to 120, oznacz go jako zły:
git bisect bad
Git kontynuuje wybór commitów, aż zidentyfikuje pierwszy zły commit. W tej demonstracji trzech commitów trzeba przetestować tylko jeden commity pośredni.
Po zakończeniu przywróć swój oryginalny branch:
git bisect reset
Podczas bisect Git zwykle sprawdza historyczne commity w detached HEAD. git bisect reset zwraca Cię do wersji, której używałeś przed dochodzeniem.
4. Zautomatyzuj dochodzenie za pomocą git bisect run
Ręczne testowanie jest przydatne, gdy błąd wymaga wizualnej inspekcji. Ale jeśli zachowanie można sprawdzić za pomocą polecenia, automatyzacja jest bardziej efektywna.
Git obsługuje git bisect run <command>. Polecenie komunikuje swój wynik za pomocą kodu wyjścia:
| Kod wyjścia | Znaczenie |
|---|---|
0 |
Dobry commit |
1–124 lub 126–127 |
Zły commit |
125 |
Nie można przetestować tego commitu |
| Inne wartości | Przerwij dochodzenie |
Te zasady pochodzą z oficjalnego podręcznika Git bisect.
Utwórz skrypt testowy poza repozytorium, np. ../check-price.php:
<?php
declare(strict_types=1);
require __DIR__ . '/git-bisect-demo/price.php';
exit(finalPrice(100, 20) === 80 ? 0 : 1);
Skrypt zakłada, że folder projektu ma nazwę git-bisect-demo i znajduje się obok check-price.php. Uruchom te polecenia z poziomu folderu projektu:
git bisect start HEAD HEAD~2
git bisect run php ../check-price.php
git bisect reset
Git uruchamia test na wybranych historycznych commitych, aż zidentyfikuje pierwszy zły commit. Ponieważ skrypt testowy znajduje się poza repozytorium, sprawdzenie starszej wersji nie usuwa go.
W prawdziwych projektach używaj stabilnego polecenia testowego lub zewnętrznego skryptu testowego, który działa z historycznymi wersjami podlegającymi badaniu.
5. Zastosuj technikę do prawdziwego projektu internetowego
Ten sam workflow działa dla pluginu WordPress, rozszerzenia Joomla, aplikacji JavaScript lub biblioteki PHP.
Załóżmy, że funkcja wycofywania transakcji jest zepsuta w najnowszej wersji, ale działała w wersji wydanej v1.4.0. Najpierw sprawdź, czy wersja jest rzeczywiście dobra, a następnie zacznij:
git bisect start HEAD v1.4.0
Jeśli projekt ma test PHPUnit, który działa na wybranych wersjach, możesz uruchomić go ręcznie:
vendor/bin/phpunit tests/CheckoutTest.php
Po każdym teście zgłaszaj git bisect good lub git bisect bad.
Kiedy test jest niezawodnie zautomatyzowany:
git bisect run vendor/bin/phpunit tests/CheckoutTest.php
git bisect reset
Historyczne commity mogą wymagać różnych wersji PHP, zależności, schematów baz danych lub narzędzi do budowania. Niepowodzenie testu z powodu niezgodności środowiska nie oznacza koniecznie regresji. Upewnij się, że Twoje środowisko testowe może odtworzyć odpowiednie wersje historyczne.

6. Co zrobić, jeśli stary commit nie może być przetestowany?
Czasami historyczna wersja nie może zostać zbudowana z niepowiązanej przyczyny. Nie oznaczaj jej automatycznie jako złej.
Użyj:
git bisect skip
Git próbuje innego kandydata. Dla zautomatyzowanych testów kod wyjścia 125 informuje Git, aby pominął ten commit.
Zbyt wiele pominiętych commitów zmniejsza precyzję. Jeśli nie da się przetestować commitu przylegającego do regresji, Git może zgłosić wielu możliwych sprawców, a nie jeden dokładny commit.
Długoterminową dobrą praktyką jest utrzymanie reprodukowalnych środowisk deweloperskich, blokowanie wersji zależności i utrzymanie krytycznych testów regresji niezależnych od niezwiązanej infrastruktury.
7. Sprawdź commit, który wprowadził błąd
Gdy Git zidentyfikuje pierwszy zły commit, sprawdź go:
git show <commit-hash>
Aby zobaczyć, które pliki się zmieniły:
git show --stat <commit-hash>
Aby sprawdzić konkretny plik:
git show <commit-hash> -- price.php
Pierwszy zły commit nie jest koniecznie jedyną przyczyną błędu. Commit może ujawniać wcześniej ukryty problem, wchodzić w interakcję z inną zmianą lub zależeć od usługi zewnętrznej, która od tamtej pory się zmieniła.
Użyj zidentyfikowanego commitu do zbadania przyczyny korzeniowej, a nie jako automatycznego dowodu, że każdy wiersz w tym commicie jest błędny.
8. Typowe problemy i rozwiązania
Błąd występuje nieregularnie
Jeśli test czasami się udaje, a czasami nie, na tym samym commicie wyniki bisect stają się niepewne. Uruchom test wielokrotnie, usuń zależności czasowe, jeśli to możliwe, i kontrolować zewnętrzne wejścia. Powtarzanie testów poprawia pewność, ale wydłuża czas dochodzenia.
Test nie powiódł się na wszystkich historycznych commitych
Potwierdź, że Twój znany dobry commit rzeczywiście jest dobry. Wyodrębnij tę wersję osobno i uruchom test przed rozpoczęciem nowej sesji bisect. Jeśli również tam nie powiedzie się, Twój test lub środowisko mogą być nieprawidłowe.
Git odmawia przełączania wersji
Niezaatrybuowane zmiany mogą uniemożliwić checkout. Sprawdź git status i zachowaj swoje zmiany przed restartem. Unikaj destrukcyjnych poleceń, takich jak git reset --hard, chyba że dokładnie rozumiesz, co je usuwa.
Historia zawiera wiele commitów scalenia
Dla złożonych repozytoriów Git obsługuje:
git bisect start --first-parent HEAD v1.4.0
To śledzi historię first-parent i może pomóc w badaniu regresji wprowadzonych przez scalenia. Zmienia to, które commity są brane pod uwagę, więc nie jest to uniwersalna zamiana na normalne bisect.
Błąd zależy od danych produkcyjnych
Nigdy nie uruchamiaj historycznego kodu aplikacji na żywej bazie danych produkcyjnej. Używaj izolowanego środowiska testowego z sanowanymi fixtures i reprodukowalnym schematem. Starsze wersje mogą zawierać migracje lub założenia niezgodne z produkcją.
9. Lista kontrolna praktycznego debugowania
- Potwierdź, że błąd jest możliwy do odtworzenia.
- Zidentyfikuj jedną wersję znaną jako działającą i jedną znaną jako nieprawidłową.
- Zachowaj niezatkierdowane zmiany.
- Zdefiniuj niezawodny test z jasnym wynikiem powodzenia lub niepowodzenia.
- Zachowaj spójność usług zewnętrznych i danych testowych.
- Użyj
git bisect skipdla rzeczywiście nie da się przetestować commitów. - Sprawdź zidentyfikowany commit i zweryfikuj przyczynę korzeniową.
- Zakończ za pomocą
git bisect reset.
Podsumowanie
Git bisect zamienia niepewne zadanie debugowania w ustrukturyzowane dochodzenie. Zamiast zgadywać, która ostatnia zmiana zepsuła aplikację, identyfikujesz wersję działającą, wersję zepsułą i pozwolisz Gitowi zawęzić historię.
Technika ta staje się szczególnie potężna, gdy jest połączona z zautomatyzowanymi testami. Regresja ukryta wśród setek commitów może być często zlokalizowana za pomocą tylko kilku sprawdzeń.
Dla programistów utrzymujących długożyjące projekty PHP, pluginy WordPress, rozszerzenia Joomla lub aplikacje JavaScript, git bisect jest jednym z najbardziej użytecznych poleceń Git poza codziennym branchingiem i mergingiem.