Git worktree nedir, paralel ajanlarda nasıl kullanılır?

Aynı klasörde iki ajan çalışınca ne bozulur?

Kodlama ajanlarını artık çoğu zaman paralel çalıştırıyoruz: bir oturum yeni bir özellik yazarken ikincisi bir hatayı düzeltiyor, alt ajanlar aynı anda farklı dosyaları değiştiriyor. Hepsi aynı klasörde çalışırsa aynı dosyaları, aynı dalı ve aynı git index’ini paylaşırlar. diffox’u geliştirdiğimiz depoda bunun bedelini birkaç kez ödedik. Her birinden bir kural çıktı:

• Yalın bir commit, başka bir ajanın işini de aldı. git commit index’te ne varsa commit eder; aynı klasördeki başka bir ajanın hazırladığı dosyalar da buna dahil. Kuralımız: paralel çalışan ajanlar yalnızca kendi dosyalarını commit eder (git commit --only <yollar>).
• Bir git checkout -b başka bir oturumun dalını değiştirdi. Ajanın kabuğu her komutta başlangıç klasörüne dönüyor ve yolu belirtilmemiş bir git komutu bir keresinde paralel bir oturumun dalını değiştirdi. Kuralımız: her git komutu yolu açıkça verir (git -C <mutlak yol>).
• Bir oturum, 40 dakikada 3 kez dal değiştiren bir klasörde değişiklik planladı. Hook yazısında anlattığımız oturum açılış hook’u bu yüzden var.
• Temizlik betiğimiz de aynı hatayı yaptı. Birleşmiş dalları temizleyen betik, temiz gördüğü her klasörü dev’e geçiriyordu. Oysa temiz bir klasör, henüz yazmaya başlamamış başka bir oturumun klasörü olabilir; betik o oturumun dalını değiştirdi. Şimdi yalnızca dev, main ya da pull request’i merge edilmiş bir daldaki klasörü taşıyor.

Hepsinin ortak noktası tek bir klasör. Worktree bu yüzden var: her ajana kendi klasörünü, kendi dalını ve kendi index’ini verir. Ama aşağıda göreceğiniz gibi her şeyi ayırmaz. Claude Code’daki isolation: worktree ayarını alt ajan yazısında anlattık. Bu yazı, ajanların ortak kullandığı depoya bakıyor.

Git worktree nedir?

Git’in belgesine göre bir depo birden çok çalışma klasörünü (working tree) destekleyebilir, böylece aynı anda birden fazla dalı açabilirsiniz. git clone ile aldığınız klasör ana worktree’dir. git worktree add ile açtıklarınız ise bağlı (linked) worktree’dir.

Bağlı worktree, HEAD ve index gibi kendine ait birkaç dosya dışında her şeyi depoyla paylaşır. Commit geçmişi bir kez durur; her worktree yalnızca dosyaların kendi kopyasını taşır. İşin çoğunu şu komutlar görür:

git worktree add -b arama ../proje-arama   # yeni klasör, yeni dal
git worktree list                          # bütün worktree'ler
git worktree remove ../proje-arama         # temizse kaldırır
git worktree prune                         # klasörü elle silinmiş olanların kaydını temizler

Git bazı hataları kendiliğinden engeller. Bir dal aynı anda yalnızca bir worktree’de açık olabilir: add, başka bir worktree’de açık olan dalı varsayılan olarak reddeder. remove da yalnızca temiz worktree’leri kaldırır; commit edilmemiş değişikliği ya da takip edilmeyen dosyası olanı silmek için --force gerekir.

Worktree ile branch farkı. Branch, bir commit’i gösteren bir isimdir. Worktree ise bir dalın dosyalarının açıldığı klasördür. Tek klasörde dal değiştirdiğinizde dosyalar o klasörde çalışan herkes için değişir. Worktree’de her ajan kendi klasöründe, kendi dalında kalır. Bir not: git’in kendi belgesi birden çok checkout’u hâlâ deneysel sayıyor ve submodule desteğinin eksik olduğunu yazıyor.

Kodlama araçlarında worktree nasıl açılır?

Beş araç da worktree’yi kendisi açabiliyor; Gemini CLI’da bu özellik deneysel ve ayarlardan açılıyor. Araçlar şu noktalarda ayrışıyor: worktree’nin nerede açıldığı, hangi commit’ten başladığı, git’in yok saydığı dosyaları (.env gibi) getirip getirmediği ve ne zaman silindiği.

Kaynak: her aracın kendi worktree belgesi, 18 Ekim 2026. “Belgede yazmıyor”: o gün okuduğumuz sayfada bu konuda bir cümle bulamadık. Codex satırı, belgenin anlattığı ChatGPT masaüstü uygulamasındaki Codex’e ait. Cursor’daki temizlik 3.5 ve sonraki sürümler için yazılmış. GitHub Copilot uygulaması da her oturuma ayrı bir worktree ve dal açıyor.

En önemli fark başlangıç noktasında. Claude Code varsayılan olarak uzak depodaki varsayılan daldan başlar; henüz push etmediğiniz commit’ler yeni worktree’de yoktur. Copilot CLI ise bulunduğunuz checkout’un HEAD’inden başlar. Codex seçtiğiniz dalın commit edilmemiş değişikliklerini bile yeni worktree’ye taşır. Ajanın neyi görmesi gerektiğine göre bu ayarı bilerek seçin.

Git’in yok saydığı dosyalar yeni worktree’ye gelmez. Claude Code ve Codex bunun için aynı adlı dosyayı okuyor: depo kökündeki .worktreeinclude. Dosya .gitignore söz dizimiyle yazılır ve yalnızca git’in yok saydığı dosyaları kopyalar. Cursor’da aynı işi .cursor/worktrees.json’daki kurulum komutları yapar; belgedeki örnek .env’yi cp ile kopyalıyor.

Bağımlılıklarda iki aracın önerisi ayrışıyor. Cursor, bağımlılıkları worktree’ye sembolik bağla getirmeyi önermiyor, çünkü bu ana worktree’de sorun çıkarabiliyor. Claude Code ise worktree.symlinkDirectories ayarıyla node_modules gibi büyük klasörleri her worktree’ye sembolik bağla getirebiliyor.

Paralel çalışma için hazır komutlar da var. Claude Code’un /batch skill’i büyük bir değişikliği, her biri kendi worktree’sinde çalışan 5 ile 30 arası alt ajana böler. Cursor’un /best-of-n komutu aynı görevi birkaç modelde çalıştırır ve her koşuya ayrı bir worktree verir. Claude Code’un ajan ekipleri (agent teams) ise üyeleri worktree’lere ayırmıyor; belge, işi her üyenin farklı dosyalardan sorumlu olacağı şekilde bölmenizi söylüyor.

Google, 18 Haziran 2026’da ücretsiz kullanıcılar ile Google AI Pro ve Ultra aboneleri için Gemini CLI’ın hizmetini durdurup onları Antigravity CLI’a yönlendirdi; ücretli API anahtarıyla ya da şirket lisansıyla Gemini CLI’ı kullanmaya devam edebilirsiniz. Antigravity’nin belgelerini 28 Ekim 2026 günü okuduk. Alt ajan belgesine göre ana ajan, başlattığı alt ajana ayrı bir Git worktree verebiliyor; alt ajan sonlandırılınca bu worktree kendiliğinden siliniyor. Worktree’nin hangi commit’ten başladığı ve .env gibi dosyaları getirip getirmediği belgede yazmıyor. Yeni bir sohbeti doğrudan ayrı bir worktree’de açmak masaüstü uygulamasında var; CLI’da bunu yapan bir bayrak bulamadık.

Worktree neyi ayırır, neyi ayırmaz?

Worktree’yi tam bir korumalı alan gibi düşünmek kolay. Oysa git her worktree’ye yalnızca birkaç şeyi ayrı verir. Gerisi ortaktır, bir kısmıyla da git hiç ilgilenmez:

Ayarlar ve hook yolu ortak. Git’e göre deponun ayar dosyası varsayılan olarak bütün worktree’lerde ortak. Depomuzda git hook’larının yeri de bu dosyada (core.hooksPath) tek bir mutlak yol olarak yazılı. Bu yüzden push’tan önce çalışan pre-push hook’u, push ettiğiniz daldaki kopyadan değil ana klasördeki kopyadan çalışıyor. 24 Ağustos 2026’da bir worktree dalında bu hook’a yeni bir kural ekledik ve 11 testi geçti. Ama aynı worktree’den yapılan push yine de geçti, çünkü ana klasör eski sürümü tutuyordu. Kimlik (user.email) gibi başka ayarlar için de aynısı geçerli; worktree’ye özel ayar için git’in extensions.worktreeConfig ayarını açmanız gerekir.

Araçların kendi izinleri de ortak olabiliyor. Claude Code’da bir worktree’de verdiğiniz “bir daha sorma” onayı ana klasörün .claude/settings.local.json dosyasına yazılır ve bütün worktree’lerde geçerli olur. Copilot CLI’da da bağlı worktree’ler ana deponun izinlerini paylaşır.

Dallar ve stash ortak. Git’e göre refs/ ile başlayan bütün referanslar worktree’ler arasında ortak, son stash da refs/stash’te tutuluyor. Adı verilmeyen bir git stash pop en son stash’i alır. Git belgesindeki bu cümleleri yan yana koyunca şu çıkıyor: bir worktree’deki git stash pop, en son stash’i başka bir worktree’deki ajan bırakmış olsa bile onu alır. Paralel ajanların çalıştığı bir depoda stash yerine geçici bir commit daha güvenli.

Git’in dışındakiler hiç ayrılmaz. Veritabanı, port, önbellek ya da yok sayılan bir veri klasörü worktree’den habersizdir. Depomuzda büyük bir ölçüm klasörünü (.runs) her worktree’ye sembolik bağla bağlıyoruz, çünkü ücretli ölçüm sonuçları orada duruyor ve worktree silinince kaybolmamalı. .gitignore’daki .runs/ kalıbı yalnızca klasörlerle eşleştiği için bu bağı yok saymadı. 21 Ağustos 2026’da git status onu her worktree’de takip edilmeyen dosya olarak gösteriyordu; bir git add -A ile commit’e girmesine bir adım kalmıştı. Veritabanı testlerimiz de ortak bir test veritabanını kullanıyor. İki worktree’deki testler aynı anda çalışmasın diye bir kilit klasörü tutuyoruz.

Oturum başındaki kontrol neden yetmez?

Bir oturum açılırken klasörün durumuna bakmak işe yarar, ama yalnızca o an için. Depomuzdaki oturum açılış hook’u, temiz dev’de açılan bir oturuma “dal açman yeter, worktree gerekmez” diyor. Aynı temiz dev’de iki oturum açılırsa ikisi de bu cevabı alır ve ikisi de aynı klasörde dal açar. İkincisi yeni dalına geçtiğinde, birincinin üzerinde çalıştığı dal da değişmiş olur.

Bu yüzden her düzenlemeden önce çalışan ikinci bir hook, dalı ve commit’i oturuma en son söylenenle karşılaştırıyor. Ayrıntısı hook yazısında; burada eklemek istediğimiz şey neyin karşılaştırıldığı. İlk akla gelen, commit edilmemiş dosya sayısıdır. Ama 12 Eylül 2026’da gördük ki oturumun kendi yaptığı tek bir düzenleme, temiz klasörü kirli gösteriyor. Kirliliğe bakan bir uyarı, ajanın kendi işini başkasınınki sanır. Hook bu yüzden yalnızca dala ve altındaki commit’e bakıyor ve işlemi durdurmadan uyarıyor.

Hook değişikliği kimin yaptığını bilemez ve bunu tahmin etmeye çalışmaz. Kendi dalını açan oturum da bir kez uyarılır, bunun kendi işi olduğunu anlar ve devam eder.

Claude Code, worktree’ye izole edilmiş bir oturum için ayrıca kendi kontrollerini çalıştırıyor. Belgesine göre ana klasördeki bir yolu hedefleyen düzenlemeleri ve git’i ana klasöre yönlendiren komutları reddediyor. Belge sınırı da açıkça yazıyor: bu kontroller bir kabuk komutunun hangi dosyalara yazdığını izlemiyor. Ana klasöre cp ya da yönlendirmeyle yazan bir komut bu kontrollere takılmıyor; belgeye göre böyle bir komut, izin ve sandbox ayarlarınıza göre değerlendiriliyor. Yani bir ajanın nereye yazabileceğini worktree değil, o ayarlar sınırlıyor.

Worktree’ler neden birikir, nasıl temizlenir?

Worktree açmak tek bir komut; kapatmak ise çoğu zaman unutuluyor. Alt ajan yazısında anlattığımız gibi 27 Ağustos 2026’da depomuzda 41 worktree birikmişti ve 37 tanesi tek bir inceleme turundan kalmıştı. Dağınıklığı insanlar değil iş akışları üretiyor. O gün bir temizlik betiği yazdık. 18 Ekim 2026 günü yeniden saydık:

Dalı merge edilmiş 34 worktree’nin hiçbirinde commit edilmemiş değişiklik yoktu. Temizlik betiğimiz tam olarak bu durumdaki worktree’leri kaldırıyor. Ama betik kendiliğinden çalışmıyor; oturum açılış hook’u yalnızca çalıştırmayı öneriyor ve biri çalıştırana kadar hepsi yerinde duruyor. 5 tanesi Codex’in klasöründe (~/.codex/worktrees) duruyordu, kalan 61 tanesi .claude/worktrees/ altındaydı. Git’in her worktree için tuttuğu klasörün oluşturulma tarihine göre, hâlâ duranların 28 tanesi tek bir günde, 15 Ekim’de açılmıştı. Bu yazının taslağı da 18 Ekim 2026 günü açılan bir worktree’de yazıldı.

Dalın merge edildiğini git söyleyemiyor. Depomuz pull request’leri squash ile merge ediyor ve squash commit’leri yeniden yazıyor. Bu yüzden merge edilmiş bir dal ne dev’in atası oluyor ne de commit’leri birebir eşleşiyor. Bir dal merge edildikten birkaç dakika sonra baktık: merge-base --is-ancestor “merge edilmedi”, git cherry “2 commit eksik” dedi; ikisi de yanlıştı. Başka bir dal, içeriğinin tamamı dev’deyken “36 commit önde” görünüyordu. Bunu bilen tek yer pull request. Temizlik betiğimiz bu yüzden GitHub’a soruyor ve yalnızca pull request’i merge edilmiş, temiz worktree’leri kaldırıyor.

Sayının kendisi de yanıltabilir. Klasörü elle silinmiş bir worktree, git worktree prune çalışana kadar listede kalır ve prunable diye işaretlenir. Oturum açılış hook’umuz önce bütün satırları birlikte sayıyordu. 8 Eylül 2026’da 26 worktree dedi, birkaç komut sonra git worktree list 7 gösterdi. Şimdi canlı ve silinebilir olanları ayrı sayıyor; canlı worktree sayısı 4’ü geçince ya da tek bir silinebilir kayıt olunca temizlik betiğini öneriyor.

Araçların kendi temizliği de birbirinden farklı. Codex varsayılan olarak son 15 worktree’sini tutuyor. Cursor varsayılan olarak makine başına 25 worktree tutuyor ve belgesine göre git worktree add ile açılmış worktree’leri de silinebilir sayıyor. Claude Code alt ajan ve arka plan worktree’lerini süpürüyor ama içinde iş kalanı bırakıyor. Gemini CLI ise temizliği size bırakıyor. Aynı depoda birden çok araç kullanıyorsanız hangisinin neyi sildiğini bilin.

Paralel ajan çalıştırırken nelere dikkat edin?

Yukarıdaki her hatadan bir madde çıktı. Hepsini bir arada şöyle özetleyebiliriz:

• Her ajana worktree gerekmez. Worktree, iki işin aynı depoyu aynı anda farklı commit’lerde istediği durum için. Tek bir oturum temiz bir dev’de çalışıyorsa dal açmak yeter. Gereksiz her worktree, sonra temizlenmesi gereken bir klasör daha demek.
• Kurulumu unutmayın. Yeni worktree temiz bir checkout’tur: bağımlılıklar, sanal ortam ve .env yoktur. Claude Code ve Gemini CLI belgeleri de ortamı her yeni worktree’de kurmanızı söylüyor. Depomuzda her worktree, ilk test koşusundan önce kendi ortamını kuruyor.
• İşi dosyalara göre bölün. Depomuzda aynı anda çalışan görevlere ayrı dosyalar verdik, her commit --only ile atıldı ve test koşuları ortak kilitle sıraya girdi.
• Paralellik bedava değil. Claude Code’un belgesine göre birkaç oturumu ya da alt ajanı aynı anda çalıştırmak token kullanımını katlıyor.

Paralel ajanların işi sonunda birer pull request olarak aynı dala gelir ve biri merge edildikçe o dal ilerler. diffox bir pull request’i incelerken değişikliği, dalın taban daldan ayrıldığı noktaya (merge base) göre ölçer; bu, GitHub’ın pull request’te gösterdiği değişikliktir. Dosyaların önceki hâlini de aynı noktadan okur. Böylece başka bir ajanın işi taban dala sonradan merge edilmişse bu incelemeye karışmaz.