Git Bisect: Hataları Giriş Ettiği Commit'i Bul
Bir özellik dün çalıştı ama bugün çalışmıyor. Git bisect'i kullanarak regresyonu getiren commit'i belirlemenin, revizyonları otomatik olarak test etmenin ve sonucu güvenli bir şekilde incelemenin yolunu öğrenin.
Git Bisect: Bir Hata İntibak Eden Commit'i Bulun
Bir web sitesi geçen hafta çalışıyordu. Bugün, bir ödeme hesaplaması yanlış, bir JavaScript bileşeni artık yanıt vermiyor veya bir PHP endpoint'i beklenmeyen veri dönüyor.
Hatanın Git geçmişinde bir yerde ortaya çıktığını biliyorsunuz, ancak depoda son çalışan sürümden bu yana onlarca veya yüzlerce commit var. Her commit'i açıp her diff'i okumak nadiren en hızlı çözümdür.
Git, tam bu durum için tasarlanmış bir araç içerir: git bisect. Her commit'i incelemek yerine, sorunu ilk kez ortaya çıkaran revizyonu belirlemek için ikili arama (binary search) kullanır. Güvenilir bir testle, araştırmayı otomatikleştirebilirsiniz.
Bu eğitimde, küçük bir PHP projesi oluşturacaksınız, kasıtlı bir regresyon (geri dönüş) ekleyeceksiniz, bunu Git bisect ile bulacaksınız ve aynı tekniği gerçek projelerde nasıl uygulayacağınızı öğreneceksiniz.
1. Git bisect nasıl çalışır
Uygulamanızın commit A'da çalıştığını ama commit H'da başarısız olduğunu düşünün. Git bisect iki referans noktasına ihtiyaç duyar: özellik kesinlikle çalışan bir iyi commit (good commit) ve hata kesinlikle bulunan bir kötü commit (bad commit).
Ara bir revizyonu checkout eder. Siz test edersiniz, çalışıp çalışmadığını bildirirsiniz ve Git kalan arama aralığını daraltır. Yaklaşık 128 aday commit için, ikili arama genellikle 128'i hepsini incelemek yerine yedi test kadar sürer, davranış tutarlı bir şekilde sınıflandırılabildiği sürece.
Resmi Git dokümantasyonu süreci ve kısıtlamalarını açıklar.
2. Tekrarlanabilir bir PHP regresyonu oluşturun
Küçük bir fiyat hesaplama fonksiyonu oluşturacağız. Framework, veritabanı, Composer paketi veya web sunucusu gerekmez. Git ve PHP CLI kurulu olmalı, ve Git commitler için yazar adınız ve e-postanız yapılandırılmış olmalı.
Bir dizin oluşturun ve depoyu başlatın:
mkdir git-bisect-demo
cd git-bisect-demo
git init
price.php oluşturun:
<?php
declare(strict_types=1);
function finalPrice(int $price, int $discount): int
{
return $price - $discount;
}
Beklenen davranış basittir: finalPrice(100, 20), 80 döndürür.
Bu çalışan sürümü commit edin:
git add price.php
git commit -m "Add working price calculation"
Sonra, ilgili olmayan bir değişiklik yapın:
echo "# Price Calculator" > README.md
git add README.md
git commit -m "Add project documentation"
Son olarak, price.php'deki hesaplamayı değiştirerek bir hata ekleyin:
<?php
declare(strict_types=1);
function finalPrice(int $price, int $discount): int
{
return $price + $discount;
}
Bozuk sürümü commit edin:
git add price.php
git commit -m "Refactor price calculation"
Proje artık üç commite sahip, sonuncusunda kasıtlı bir regresyon var.
3. Regresyonu manuel olarak bulun
Çalışma ağacınızın temiz olduğunu doğrulayarak başlayın:
git status --short
Komut hiçbir çıktı üretmemeli. Eğer commit edilmemiş çalışmanız varsa, bisect'e başlamadan önce bunu uygun şekilde commit edin veya stash'leyin.
Şimdi Git bisect'i başlatın:
git bisect start
git bisect bad HEAD
git bisect good HEAD~2

Burada, HEAD bozuk revizyondur, HEAD~2 ise ilk çalışan commit'i işaret eder. Git ara commiti checkout eder.
Hesaplamayı test edin:
php -r 'require "price.php"; echo finalPrice(100, 20), PHP_EOL;'
Çıktı 80 ise, revizyonu iyi olarak işaretleyin:
git bisect good
Eğer 120 ise, kötü olarak işaretleyin:
git bisect bad
Git, ilk kötü revizyonu belirleyene kadar commitleri seçmeye devam eder. Bu üç commitlik gösteride, sadece bir ara revizyon test edilmesi gerekir.
Bittiğinde, orijinal branch'inize dönün:
git bisect reset
Bisect sırasında Git normalde geçmiş revizyonları detached HEAD durumunda checkout eder. git bisect reset, araştırma öncesinde kullanıyordunuz revizyona size geri döndürür.
4. git bisect run ile araştırmayı otomatikleştirin
Manuel test, bir hata görsel inceleme gerektirdiğinde faydalıdır. Ama davranış bir komutla kontrol edilebiliyorsa, otomasyon daha verimlidir.
Git git bisect run <command>'i destekler. Komut, sonucunu bir çıkış kodu (exit code) ile bildirir:
| Çıkış kodu | Anlamı |
|---|---|
0 |
İyi revizyon |
1–124 veya 126–127 |
Kötü revizyon |
125 |
Bu revizyon test edilemez |
| Diğer değerler | Araştırmayı iptal et |
Bu kurallar resmi Git bisect kılavuzundan gelmektedir.
Depo dışında bir test script'i oluşturun, örneğin ../check-price.php:
<?php
declare(strict_types=1);
require __DIR__ . '/git-bisect-demo/price.php';
exit(finalPrice(100, 20) === 80 ? 0 : 1);
Script, proje klasörünün git-bisect-demo olarak adlandırıldığını ve check-price.php'in yanında olduğunu varsayar. Bu komutları proje klasörü içinden çalıştırın:
git bisect start HEAD HEAD~2
git bisect run php ../check-price.php
git bisect reset
Git, ilk kötü commit belirlenene kadar seçilen geçmiş revizyonlarda testi çalıştırır. Test script'i depo dışında olduğu için, daha eski bir revizyona checkout edilmesi script'i silmez.
Gerçek projeler için, araştırma altındaki geçmiş revizyonlarla çalışan kararlı bir test komutu veya harici bir test script'i kullanın.
5. Tekniği gerçek bir web projesine uygulayın
Aynı iş akışı bir WordPress eklentisi, Joomla uzantısı, JavaScript uygulaması veya PHP kütüphanesi için de çalışır.
Varsayalım ki ödeme özelliği en son sürümde bozuk, ama v1.4.0 sürümünde çalışıyordu. Önce sürümün gerçekten iyi olduğunu doğrulayın, sonra başlatın:
git bisect start HEAD v1.4.0
Eğer projenin seçili revizyonlar generalinde çalışan bir PHPUnit testi varsa, bunu manuel olarak çalıştırabilirsiniz:
vendor/bin/phpunit tests/CheckoutTest.php
Her testten sonra git bisect good veya git bisect bad bildirin.
Test güvenilir bir şekilde otomatikleştirilebildiğinde:
git bisect run vendor/bin/phpunit tests/CheckoutTest.php
git bisect reset
Geçmiş commitler farklı PHP sürümleri, bağımlılıklar, veritabanı şemaları veya derleme araçları gerektirebilir. Ortam uyumsuzluğu nedeniyle bir testin başarısız olması regresyonu göstermek zorunda değildir. Test ortamınızın, ilgili geçmiş sürümleri yeniden üretebildiğinden emin olun.

6. Eski bir commit test edilemezse ne olur?
Bazen bir geçmiş revizyon, ilgisiz bir nedenle derlenemez. Bunu otomatik olarak kötü olarak işaretlemeyin.
Şunu kullanın:
git bisect skip
Git başka bir aday dener. Otomatik testler için, çıkış kodu 125 Git'e revizyonu atlamasını söyler.
Çok fazla commit atlamak hassasiyeti azaltır. Eğer test edilemeyen bir commit regresyonun yanındaysa, Git tek bir kesin commit yerine birden fazla olası suçlu raporlayabilir.
Uzun vadeli iyi bir pratik, yeniden üretülebilir geliştirme ortamlarını korumak, bağımlılık sürümlerini kilitlemek ve kritik regresyon testlerini ilgisiz altyapıdan bağımsız tutmaktır.
7. Hata Eden Commit'i İnceleyin
Git ilk kötü commit'i belirlediğinde, onu inceleyin:
git show <commit-hash>
Hangi dosyaların değiştiğini görmek için:
git show --stat <commit-hash>
Belirli bir dosyayı incelemek için:
git show <commit-hash> -- price.php
İlk kötü commit, hatanın tek nedeni değildir. Bir commit önceden gizli bir sorunu ortaya çıkarabilir, başka bir değişiklikle etkileşime girebilir veya daha sonra değişen bir harici hizmete bağımlı olabilir.
Tespit edilen commit'i kök nedeni araştırmak için kullanın, o commit'teki her satırın yanlış olduğu kanıtı olarak değil.
8. Yaygın sorunlar ve çözümler
Hata tutarsız ortaya çıkıyor
Eğer bir test aynı revizyonda bazen geçiyor bazen başarısız oluyorsa, bisect sonuçları güvenilmez hale gelir. Testi birden fazla kez çalıştırın, mümkünse zamanlama bağımlılıklarını kaldırın ve harici girdileri kontrol edin. Tekrarlı test güven artırır ama araştırma süresini uzatır.
Test her geçmiş revizyonda başarısız oluyor
Bildiğiniz iyi commit'in gerçekten iyi olduğunu doğrulayın. O revizyona ayrı ayrı checkout edin ve yeni bir bisect oturumu başlamadan önce testi çalıştırın. Orada da başarısız oluyorsa, testiniz veya ortamınız yanlış olabilir.
Git revizyon değiştirmeyi reddediyor
Commit edilmemiş değişiklikler checkout'i engelleyebilir. git status kontrol edin ve yeniden başlamadan önce değişikliklerinizi koruyın. git reset --hard gibi yıkıcı komutlardan, tam olarak ne attıklarını bilmeden kaçının.
Geçmiş çok sayıda merge commit içeriyor
Karmaşık depolar için Git şunu destekler:
git bisect start --first-parent HEAD v1.4.0
Bu, first-parent geçmişini takip eder ve merge'ler yoluyla eklenen regresyonları araştırmaya yardımcı olabilir. Hangi commitlerin değerlendirildiğini değiştirir, bu yüzden normal bir bisect için evrensel bir değiştirme değildir.
Hata üretim verilerine bağlı
Asla geçmiş uygulama kodunu canlı bir üretim veritabanı karşısında çalıştırmayın. Temizlenmiş fixture'lar ve yeniden üretülebilir şema ile yalıtılmış bir test ortamı kullanın. Eski revizyonlar üretimle uyumsuz migration'lar veya varsayımlar içerebilir.
9. Pratik bir hata ayıklama kontrol listesi
- Hatanın tekrarlanabilir olduğunu onaylayın.
- Çalışan bilinen bir revizyon ve başarısız bilinen bir revizyon belirleyin.
- Commit edilmemiş çalışmayı koruyun.
- Net bir geçme/başarısız olma sonucu olan güvenilir bir test tanımlayın.
- Harici servisleri ve test verilerini tutarlı tutun.
- Gerçekten test edilemeyen revizyonlar için
git bisect skipkullanın. - Tespit edilen commit'i inceleyin ve kök nedeni doğrulayın.
git bisect resetile bitirin.
Sonuç
Git bisect, belirsiz bir hata ayıklama görevini yapılandırılmış bir araştırmaya dönüştürür. Hangı yakın değişikliğin uygulamayı bozduğunu tahmin etmek yerine, çalışan bir revizyon, bozuk bir revizyon belirlersiniz ve Git geçişi daraltır.
Bu teknik, otomatik testlerle birleştirildiğinde özellikle güçlü olur. Yüzlerce commit arasına gizlenmiş bir regresyon, genellikle sadece birkaç kontrolle yerelleştirilebilir.
Uzun ömürlü PHP projelerini, WordPress eklentilerini, Joomla uzantılarını veya JavaScript uygulamalarını sürdüren geliştiriciler için, git bisect, günlük branching ve merging'in ötesindeki en yararlı Git komutlarından biridir.