Versiyon‑Kontrol‑Uyumlu Dosya Dönüştürme

Bir geliştirme ekibi dokümantasyon, tasarım varlıkları veya veri dosyalarını kaynak kodun yanına depoladığında, dosya formatı seçimi versiyon‑kontrol sisteminin kullanılabilirliğini ya iyileştirir ya da baltalar. Kötü seçilmiş bir dönüşüm depo boyutunu şişirebilir, diff çıktısını okunmaz hâle getirebilir ve otomatik derlemeleri kırılgan hâle sokabilir. Bu makale, Git’in sağladığı temiz geçmiş ve yeniden üretilebilirliği feda etmeden dosyaları nasıl dönüştürebileceğinize dair teknik hususları ele alıyor. Rehber, gerçek dünya iş akışlarına dayanmakta ve hızlı, gizlilik‑bilinçli bir dönüşüm gerektiğinde convertise.app gibi bulut‑tabanlı bir dönüştürücü kullandığınızı varsayıyor.

Neden Geleneksel Dönüşümler Git ile Çelişir

Git, düz‑metin değişikliklerini satır‑satır izlemekte üstünlük gösterir. Ancak ikili (binary) bloblar, opak anlık görüntüler olarak saklanır; herhangi bir değişiklik tüm dosyanın yeniden yüklenmesine yol açar ve depo şişer. Ayrıca, bir çok dönüşüm hattı nondeterministik çıktı üretir—zaman damgaları, GUID’ler veya gömülü meta veriler her çalıştırmada farklı olur, bu da git diff içinde yanlış pozitiflere ve birleştirme çatışmalarının çözümünü zorlaştırır. Büyük ikili dosyalar ve nondeterministik davranışın birleşimi, tek bir gerçek kaynağa sahip olmanın faydasını hızla yok eder.

Versiyon‑kontrol‑uyumlu bir dönüşüm iş akışı üç temel sorunu çözer:

Boyut şişmesi – depoda megabaytlarca üretilmiş varlık saklamaktan kaçının.
Diff bulanıklığı – Git’in anlamlı farkları gösterebileceği bir formatta çıktı tutun.
Yeniden üretilebilirlik – aynı kaynağın her zaman aynı çıktıyı üretmesini sağlayın, böylece CI süreçleri deterministik kalır.

Dönüşüm‑Hazır Formatları Erken Seçin

En etkili hafifletme, Git’in güçlü yönlerine uygun bir hedef format seçmekle olur. İşte en yaygın kaynak‑hedef eşleşmeleri ve neden önemli oldukları:

Markdown → HTML / PDF – Markdown düz metindir; HTML hâlâ metin‑tabanlıdır, bu yüzden diff işlemi çalışır. PDF gerekli olduğunda, zaman damgalarını temizleyen deterministik bir LaTeX hattı üzerinden oluşturun.
SVG → PNG – SVG vektördür ve diff yapılabilir. PNG yalnızca son dağıtım için dönüştürün; SVG’yi sürüm geçmişi için depoda tutun.
CSV → Parquet – CSV’yi insanlar gözden geçirsin; analitik amaçlı Parquet üretmek için otomatik bir adım kullanın. Parquet dosyaları ikili olduğundan, bir veri‑gölü kovasına, depoya değil, konulmalıdır.
Tasarım kaynakları (Figma, Sketch) → PNG / PDF – Orijinal kaynak dosyalarını tutun (genellikle ikili, ama bir versiyon‑kontrol‑projeye paketlenir). Yayınlama sırasında sadece dışa aktarım yapın ve dışa aktarılanları ayrı bir artefakt deposunda saklayın.

Bir dönüşüm kaçınılmaz olarak ikili bir dosya üretirse (ör. derlenmiş PDF), kaynağı (LaTeX, Markdown, SVG) Git’te tutun ve ikiliyi türetilmiş bir artefakt olarak değerlendirin. Bu ayrım hem boyut hem de diff sorunlarını çözer.

Deterministik Dönüşüm: Gizli Değişkenliği Ortadan Kaldırma

İkili bir dosyanın depoda bulunması gerektiğinde bile dönüşümü tekrarlanabilir hâle getirebilirsiniz. Şu adımları izleyin:

Zaman damgalarını temizleyin – Çoğu dönüştürücü çalıştırıldığında geçerli tarihi gömer. exiftool -AllDates= ... gibi bir post‑process betiğiyle bunları silin.
Meta veri sıralamasını normalleştirin – Bazı araçlar sözlük girdilerini nondeterministik sırayla yazar. Dönüştürücünün bir “sıralama” seçeneği varsa onu kullanın; yoksa çıktıyı kararlı bir serileştiriciden geçirin (jq -S JSON için, xsltproc XML için).
Sıkıştırma ayarlarını sabitleyin – Kayıpsız, deterministik bir sıkıştırma algoritması seçin (ör. sabit bir seed ile zlib). Rastgele seed içeren ayarlardan kaçının.
Satır sonlarını kontrol edin – Tüm dosyalarda LF (\n) kullanın; Windows satır sonları (\r\n) diff’leri bozar.
Tekrarlanabilir bir ortam kullanın – Dönüşümü, tüm kütüphane sürümlerini sabitleyen bir Docker konteyneri içinde çalıştırın. Böylece “benim makinemde çalışıyor” farkı ortadan kalkar.

Dönüşüm hattını saf‑fonksiyon gibi tutarak aynı kaynak için her çalıştırmada aynı hash’i elde edersiniz; bu da güvenilir git diff --binary ve basit CI önbellekleme sağlar.

Dönüşümü Git İş Akışına Entegre Etmek

Dönüşüm adımlarını bütünleştirmenin iki yaygın modeli vardır:

1. Pre‑commit Kancasıyla Üretim

Pre‑commit kancası, dosyalar index’e eklenmeden önce dönüştürücüyü çalıştırabilir. Kanca, türetilmiş artefakti tekrar index’e yazar; böylece depo her zaman en güncel dönüşümü içerir. Bash örneği:

#!/usr/bin/env bash
# Pre‑commit kancası: Markdown’tan PDF üret
files=$(git diff --cached --name-only --diff-filter=ACM | grep '\.md$')
for f in $files; do
  out=${f%.md}.pdf
  curl -X POST -F "file=@$f" https://api.convertise.app/convert -F "target=pdf" -o "$out"
  # Dosyayı deterministik tutmak için zaman damgalarını temizle
  exiftool -AllDates= "$out" -overwrite_original
  git add "$out"
done

Kanca dönüşümü otomatik hâle getirir ve her commit’te tutarlı bir ikili olmasını garantiler.

2. Yalnızca CI Üretim Artefaktları

İkililer büyükse, bunları CI sunucusunda üretmek ve bir artefakt deposuna (GitHub Packages, Artifactory vb.) itmek genellikle daha iyidir. Kaynak Git’te kalır, sürümler de üretilen dosyaları artefakt mağazasından çeker. Bu model depo şişmesini önlerken, son kullanıcıya hazır varlıkları sunar.

Büyük İkili Dosyaları Git LFS ile Yönetmek

Büyük varlıkları (yüksek çözünürlüklü görseller, kitap için derlenmiş PDF’ler, 3D model önizlemeleri) versiyonlamak zorundaysanız, Git LFS (Large File Storage) standart çözümdür. Başarının anahtarları:

Yalnızca gerekli ikilileri izleyin. Dönüşüme hazır kaynak dosyaları ana depoda, LFS ise son çıktıyı saklasın.
Adlandırma kuralları uygulayın (*.pdf.lfs, *.png.lfs) böylece geliştiriciler hangi dosyaların LFS yönetildiğini bilir.
.gitattributes içinde bir boyut sınırı koyun (ör. *.pdf filter=lfs diff=lfs merge=lfs -text) böylece büyük dosyaların doğrudan commit edilmesi önlenir.

Deterministik dönüşümle birleştirildiğinde, Git LFS her sürüm için yalnızca bir kopya saklar; aynı çıktılar farklı dallarda aynı LFS nesnesini paylaşır, bant genişliği tasarrufu sağlar.

Pre‑commit ve Pre‑push Kancalarıyla Otomasyon

Temel üretim kancasının ötesinde, doğrulama adımları ekleyerek regresyonları erken yakalayabilirsiniz:

Checksum doğrulaması – Dönüşümden sonra SHA‑256 hash’i hesaplayıp bir .checksums dosyasındaki değerle karşılaştırın. Fark varsa, dönüşüm nondeterministik demektir.
Şema doğrulaması – Veri dosyaları (CSV → Parquet) için JSON Schema veya Avro tanımı kullanarak çıkışın beklenen sütun tiplerine uyduğunu kontrol edin.
Erişilebilirlik kontrolü – Üretilen PDF veya HTML üzerinde otomatik bir a11y aracı çalıştırarak alt‑metin ve başlık hiyerarşisinin korunup korunmadığını teyit edin.

Bu kontroller yerel olarak çalışır, merkezi depoya kod ulaşmadan anında geri bildirim verir.

Meta Veri ve Köken Bilgisini Koruma

İkili diff’lenemez olsa bile, yan dosyada kritik köken bilgisini saklayabilirsiniz. Her üretilen varlıkla birlikte bir JSON manifestosu tutun:

{
  "source": "docs/chapter1.md",
  "converter": "convertise.app",
  "timestamp": "2026-05-24T12:34:56Z",
  "options": {
    "pdfVersion": "1.7",
    "embedFonts": true
  },
  "hash": "a3f5c2..."
}

Manifest düz metindir, tamamen versiyonlanır ve CI süreçlerinin binary’nin iddia edilen kaynağa uygunluğunu doğrulamasında kullanılabilir.

Dönüşüm Doğruluğunu Test Etmek

Sağlam bir iş akışı, yeni üretilecek ikilileri bilinen‑iyi bir temel ile karşılaştıran regresyon testleri içerir. İkili diff’leri gürültülü olduğundan şu kombinasyonu kullanın:

Piksel‑piksel görüntü karşılaştırması tolerans eşiğiyle (compare -metric RMSE).
PDF yapısal karşılaştırması diff-pdf --output-diff ile görsel farkları vurgulama.
Metin çıkarma kontrolleri – PDF üzerinde OCR çalıştırıp elde edilen düz metni kaynakla karşılaştırma.

Bu testleri bir GitHub Actions işine entegre edin; herhangi bir sapma eşik değerini aşarsa PR başarısız olur.

Mini‑Vaka Çalışması: Teknik Dokümantasyon Sitesi

Bir yazılım ekibi, Hugo ile çalışan kamuya açık bir dokümantasyon sitesi yönetiyor. Kaynak belgeler Markdown’da yazılıyor; site ayrıca indirilebilir PDF el kitapları da sunuyor. İlk iş akışı PDF’leri doğrudan depoya kaydediyordu. Zamanla depo 1,5 GB’a ulaştı ve geliştiriciler PDF’deki birleştirme çatışalarından şikayetçi oldu.

Çözüm adımları:

Depoda yalnızca .md dosyalarını tutun.
Pre‑commit kancası ekleyerek convertise.app ile her Markdown dosyasından PDF üretin, zaman damgalarını temizleyin ve yanına bir .md5 dosyası olarak SHA‑256 hash’i yazın.
PDF’leri saklamak için Git LFS’i yapılandırın (*.pdf filter=lfs).
Aynı dönüşümü CI’da çalıştıran bir iş ekleyin; hash’in .md5 ile eşleştiğini doğrulayın ve PDF’leri bir S3 kovasına yayınlayın.
Site, derleme zamanında PDF’leri S3’ten çeker.

Sonuç: depo boyutu %78 azaldı, diff’ler again anlamlı hâle geldi ve PDF üretimi tamamen yeniden üretilebilir oldu; dallar arasında “PDF kayması” sorunu ortadan kalktı.

En İyi Uygulamalar Özeti

Kaynak‑dostu formatları (Markdown, SVG, CSV) Git’te tutun; ikilileri türetilmiş artefakt olarak değerlendirin.
Dönüşümleri deterministik yapın; zaman damgalarını temizleyin, sıkıştırmayı sabitleyin ve konteyner‑tabanlı ortamlar kullanın.
Küçük varlıklar için pre‑commit, büyük varlıklar için CI üretim kancalarıyla otomasyonu sağlayın.
Git LFS’i yalnızca gerekli ikililer için ve net bir adlandırma şemasıyla kullanın.
Köken bilgilerini yan‑JSON manifestolarında saklayarak denetlenebilirliği artırın.
Checksum, şema ve görsel regresyon testleri ile düzenli doğrulama yapın.

Dönüşüm seçimlerini versiyon kontrolünün güçlü yönleriyle hizalayarak ekipler depolarını hafif, geçmişi net ve gerektiğinde yüksek kaliteli ikili varlıkları sorunsuz bir şekilde sunabilir. Bu yaklaşım hem kod‑odaklı projeler hem de içerik‑ağır dokümantasyon siteleri için geçerlidir ve gizlilik‑öncelikli bulut dönüştürücülerden convertise.app gibi güvenilir, an‑iste dönüşümler gerektiğinde sorunsuz entegrasyon sağlar.

Versiyon Kontrolüne Uygun Dosya Dönüştürme: Temiz Git Geçmişleri ve Tekrarlanabilir Varlıklar İçin Stratejiler