Gitbrella

gitbrella, bulut eşitleme klasörlerinde duran git depolarındaki hasarı bulan ve onaran bir komut satırı aracı. Depoyu değiştirmeden ve buluttan hiçbir dosya indirmeden kontrol ediyor; tek doğru onarımı olan hasarı düzeltiyor; sorunu kalıcı olarak bitirmek için de .git dizinini eşitlenen klasörün dışına taşıyor.

Problem

iCloud Drive, Dropbox, OneDrive, Google Drive ve Syncthing dosyaları tek tek eşitliyor. Git ise .git dizininin bir bütün olarak değişmesini bekliyor. Bu uyumsuzluk eşitlenen klasördeki depolarda tanıdık izler bırakıyor:

• .git/index 2 veya refs/heads/main 2 gibi çakışma kopyaları
• kaybolmuş bir index ve yanında kalmış eski bir index.lock
• yalnızca bulutta duran, diske hiç inmemiş nesne dosyaları
• index’in boş yeniden kurulması yüzünden bir sonraki commit’te bütün dosyaların silinmiş görünmesi

Git’in kendi SSS’i depoyu eşitlenen klasörde tutmamayı öneriyor. Yine de varsayılan ayarlar depoları sürekli oraya götürüyor: macOS’te iCloud’a eşitlenen Masaüstü ve Belgeler, Windows’ta OneDrive klasör yedeği ya da Documents/GitHub. Hasar çoğu zaman sessiz kalıyor ve ancak yanlış bir commit atıldığında fark ediliyor.

Bu projede odaklandığım noktalar

• Kontrolün depoya hiç yazmaması ve buluttaki dosyaları indirmemesi
• Sağlam depolarda yanlış alarm vermemek; bir kilidi ancak hiçbir git süreci tutamıyorsa hasar saymak
• Yalnızca tek doğru cevabı olan hasarı onarmak, gerisini komutuyla birlikte kullanıcıya bırakmak
• Her değişikliği geri alınabilir tutmak
• Commit hook’ları ve yapay zekâ ajanları için kararlı çıkış kodları ve sürümlenmiş JSON çıktısı sunmak

Komutlar

check çoğu depoda bir saniyeden kısa sürede biter. Çıkış kodu 0 sağlam, 1 hasar bulundu, 2 kontrol çalışamadı anlamına geliyor. fix ve move-out, --apply verilmeden yalnızca planı gösteriyor.

Öne çıkan özellikler

Salt okunur kontrol

Kontrol sırasında git, isteğe bağlı kilitler kapalı (GIT_OPTIONAL_LOCKS=0), otomatik gc ve bakım devre dışı, yalnızca okuyan komutlarla çalışıyor. macOS’te araç kendi süreci için isteğe bağlı bulut indirmesini kapatıyor; işletim sistemi buna izin vermezse kontrol hiç başlamıyor. Kısmi klonlarda eksik nesneler ağdan çekilmiyor. Riskli senaryolar için uçtan uca testler, kontrolden önce ve sonra her dosyanın boyutunu, değişiklik zamanını ve inode’unu kaydedip aynı kalmasını şart koşuyor.

Güvenli onarım ve kalıcı çözüm

fix, örneğin HEAD ile birebir aynı olan bir index kopyası gibi tek bir doğru cevabı olan durumları onarıyor. Belirsiz durumları değiştirmeden çalıştırılacak komutla birlikte raporluyor. move-out ise .git dizinini eşitlenen klasörün dışına alıp yerine ona işaret eden bir .git dosyası bırakıyor. Böylece eşitleme istemcisi dosyaları taşımaya devam ediyor, git geçmişi ise eşitlemenin dışında kalıyor.

Commit hook’u ve ajan koruması

Bir pre-commit hook’u olarak çalıştığında, hasarlı bir depoda commit’i durduruyor; özellikle boşalmış bir index’in bütün dosyaları “silindi” olarak kaydetmesini engelliyor. pre-commit, lefthook, husky ve Overcommit ile birlikte kullanılabiliyor. gitbrella hook --for claude|codex, Claude Code ve Codex’in hook protokolünü konuşuyor: hasarlı depoda yazan git komutlarını ve .git içine yazmayı durduruyor, okumaya, dosya düzenlemeye ve onarıma izin veriyor.

Kurulum

macOS ve Linux’ta, amd64 ve arm64 mimarilerinde çalışıyor; git 2.31 veya daha yenisi gerekiyor.

brew install aliyilmazco/tap/gitbrella

go install github.com/aliyilmazco/gitbrella/cmd/gitbrella@latest

Her sürüm SHA-256 sağlama listesi, cosign ile anahtarsız imza, arşiv başına SPDX SBOM ve GitHub derleme kökeni (build provenance) kanıtıyla yayımlanıyor.

Sınırlar

• Windows ve Windows üzerindeki OneDrive henüz test edilmedi.
• iCloud’un iki cihaz arasında kendisinin ürettiği çakışma kopyaları testlerde birebir yeniden üretilemedi; algılama aynı adlandırmayı izleyen kopyalarla doğrulanıyor.
• fix yalnızca tek doğru cevabı olan hasarı onarıyor. Kalıcı çözüm move-out.

Bağlantılar

• GitHub deposu: github.com/aliyilmazco/gitbrella
• Son sürüm: v1.0.2
• Homebrew: brew install aliyilmazco/tap/gitbrella
• Platform: macOS ve Linux (amd64, arm64)
• Lisans: MIT
• Belgeler: README, Türkçe dahil 18 dilde

Mühendislik notları

Bu tür bir araçta asıl zorluk hasarı bulmak değil, sağlam depoda hiçbir şey bulmamak. Çalışan git süreçlerinin tuttuğu kilitler, git’in geçici dosyaları ve başka araçların .git içine bıraktığı dosyalar hasar sayılmamalı. Araç 89 sağlam ve aktif depoda çalıştırıldığında hiç hasar raporlamadı. Aynı titizlik onarım tarafında da geçerli: bir onarım ancak geri alınabiliyorsa ve tek doğru sonucu varsa otomatik yapılıyor.