Nethür
Giriş yap
macOS yakında

Blog · 5 Kasım 2026

Claude Code worktree’leri: kapsamlı bir açıklama

Claude Code’daki git worktree’ler için sade bir rehber: neyi izole ederler, nereye giderler ve işi kaybetmeden nasıl oluşturulur, incelenir ve kaldırılırlar.

Tek bir main dalının her görev için birer tane olmak üzere üç Nethür worktree’sine ayrıldığını gösteren diyagram

Bir Claude Code worktree’si, içinde Claude Code çalıştırdığınız sıradan bir git worktree’sidir. Git reponun ikinci bir kopyasını başka bir branch’te checkout eder, Claude Code o dizini çalışma ağacı olarak kullanır ve ana checkout’unuz dokunulmadan kalır. Konum, `git worktree add` komutuna verdiğiniz yol ya da sizin için oluşturan aracın yönetilen dizinidir.

“Claude Code worktree” kulağa açmanız gereken bir özellik gibi geliyor. Çoğu zaman iş bundan daha basit: worktree git’in oluşturduğu bir dizindir ve Claude Code başlattığınız dizinde dosyaları düzenleyen bir süreçtir. Bu iki gerçeği birleştirin, izole ajan oturumlarını elde edersiniz.

Bu ayrım önemli çünkü internette üç farklı şey birbirine karışıyor: git worktree’ler, Claude Code’un kendi uygulamalarındaki worktree özellikleri ve sizin için worktree oluşturan çalışma alanı araçları. Aynı adı ve amacı paylaşıyorlar, ama konum, temizlik ve inceleme hikâyesi dizini kimin oluşturduğuna göre değişiyor. Hangi katmanın işi yaptığını bilmek, worktree’nin nerede oluşacağını ve temizliğini kimin üstleneceğini de belirler.

Bir git worktree aslında nedir?

Normal bir clone’un tek bir çalışma ağacı vardır: editörünüzde gördüğünüz dosyalar. Bir git worktree aynı reponun aynı anda birden fazla çalışma ağacına sahip olmasını sağlar; her biri farklı bir branch’te. Nesne veritabanı ve remote’lar paylaşılır; checkout edilmiş dosyalar ve index paylaşılmaz.

git worktree list
# /Users/you/app             abc1234 [main]
# /Users/you/app-fix-login   def5678 [fix/login]
  • Her worktree’nin kendi branch’i, HEAD’i, index’i ve diskteki dosyaları vardır.
  • Aynı branch’i iki worktree’de aynı anda checkout edemezsiniz.
  • Bir worktree’yi silmek dizini ve checkout’unu kaldırır, branch geçmişini değil.
  • Her worktree hâlâ aynı repodur, bu yüzden commit’ler, fetch’ler ve push’lar aynı nesneleri görür.

Bu tam da bir ajanın ihtiyaç duyduğu izolasyondur. Claude Code kendi worktree’sinde okuyabilir, düzenleyebilir, test çalıştırabilir ve commit edebilir; açık tuttuğunuz checkout’a dokunmaz. Ajan bir şeyi bozarsa dizini silersiniz ve ana branch’iniz sizde kalır.

Claude Code neden bir worktree’den faydalanır?

Bir ajan oturumu, dosyalara dokunan bir sohbet değildir. Komutlar çalıştırır, dev server başlatır, üretilmiş dosyalar yazar, değişiklikleri stage’ler ve bazen branch değiştirir. Tek bir checkout’taki iki oturum tüm bu durumu paylaşır. Hata nadiren dramatiktir: bir test yanlış koda karşı geçer, bir formatter diğer ajanın işini yeniden yazar veya bir commit her iki görevin dosyalarını içerir.

Bir worktree bu paylaşılan durum hatalarını ayrı dizinlere dönüştürür. Bedeli, her yeni worktree’nin temiz başlamasıdır: node_modules yok, .env yok, yerel veritabanı yok. Bu rehberin geri kalanı çoğunlukla bu bedeli bilinçli olarak ödemekle ilgili.

Claude Code’da worktree modu var mı?

Claude Code CLI’ın bir worktree içinde çalışmak için özel bir moda ihtiyacı yoktur. Oturum sınırı çalışma dizinidir. ../app-fix-login içinde claude başlatın, oturum orada okur ve yazar; ../app-fix-billing içinde bir tane daha başlatın, farklı bir branch’i ve farklı bir dosya kümesi olur. Komutu hangi dizinde çalıştırdığınız, oturumun sınırını belirler.

Diğer Claude Code yüzeyleri worktree’leri sizin için yönetir. Masaüstü uygulaması izole git worktree’lerde paralel oturumlar çalıştırabilir; ajan ekipleri veya subagent’lar bir oturum içinde iş devredebilir. Bunlar kolaylık katmanlarıdır: bir checkout oluşturur, ajanı içine koyar ve yolu gizler. Öngörülebilir bir konuma ihtiyacınız varsa worktree’yi kendiniz oluşturun ve içinde Claude Code başlatın.

Claude Code worktree’si nerede durmalı?

Konum, worktree’yi kimin oluşturduğuna bağlıdır. Elle kurulumda git worktree add komutuna bir yol verirsiniz. İki kural iyi çalışır: ana checkout’un yanında kardeş bir dizin veya reponun dışında ayrı bir worktrees/ klasörü.

# sibling next to the main checkout
git worktree add ../app-fix-login -b fix/login origin/main

# or a dedicated root outside the repo
git worktree add ~/worktrees/app/fix-login -b fix/login origin/main

Worktree’leri ana checkout’un dışında tutun. Repo içindeki bir worktree her aramada görünür, editör indekslemesini karıştırır ve yanlışlıkla commit edilebilir. Bir araç repo içindeki gizli bir klasörde worktree oluşturuyorsa, ona güvenmeden önce o klasörün gitignore’lu olup olmadığını kontrol edin.

Nethür worktree’leri kendi yönetilen dizininde oluşturur ve yolu sizin için takip eder. Claude Code, GSD veya düz git worktree add ile oluşturduğunuz worktree’ler varsa Nethür onları taşımanızı istemek yerine harici worktree olarak gösterebilir. Ayarlar → Genel → Çalışma Alanı hangi harici kaynakların görüneceğini ve hangi konum köklerinin taranacağını kontrol eder.

Yolları elle yönetmek istemiyorsanız Nethür gibi bir git worktree GUI’si worktree’leri sizin için oluşturup takip edebilir ve temizleyebilir; üstelik diskte normal bir checkout bırakmaya devam eder.

Bir worktree oluşturun ve Claude Code başlatın

Ajan geçen haftanın koduna karşı çalışmasın diye güncel bir temel ref’ten başlayın.

git fetch origin
git worktree add ../app-fix-login -b fix/login origin/main
cd ../app-fix-login
claude

Her worktree için benzersiz bir branch adı kullanın. Aynı görevde ikinci bir ajan istiyorsanız prompt aynı olsa bile farklı branch’le ikinci bir worktree oluşturun. İki sonucu karşılaştırılabilir ve bağımsız merge edilebilir yapan şey branch’tir. Böylece aynı prompt’u iki kez çalıştırsanız bile iki sonucu yan yana koyabilirsiniz.

Nethür’de aynı adım bir diyalogdur: worktree oluştur, görevi adlandır, başlangıç ref’ini seç ve ajanı seç. Nethür git fetch ve git worktree add komutlarını arka planda çalıştırır, oluşturulurken çalışma alanını gösterir ve ajanı yeni checkout’ta açar. Worktree belgeleri başlangıç ref’i seçiciyi, klasör çalışma alanlarını ve bağlı issue’ları anlatıyor.

Bağımlılıklar, env dosyaları ve portlar

Taze bir worktree temiz bir checkout’tur, yani git’in yok saydığı her şey eksiktir. Bununla başa çıkmanın üç yolu var ve çoğu ekip sonunda üçünü birlikte kullanıyor.

  • Worktree başına kurulum. Doğru ve basit, ama her ajan kendi node_modules’üne ihtiyaç duyduğunda yavaş ve disk açısından maliyetli.
  • Ağır, yeniden üretilebilir dizinleri paylaşın. Nethür’ün Worktree Shared Paths özelliği gitignore’lu dizinleri ana checkout’tan oluşturur; repo düzeyinde tanımlar için nethur.yaml içindeki worktree.sharedDirectories kullanılır.
  • Küçük, worktree’ye özgü dosyaları kopyalayın. .worktreeinclude kopyalanacak gitignore’lu dosya ve dizinleri listeler, örneğin .env veya yerel editör ayarları; böylece her worktree kendi kopyasına sahip olur.
# nethur.yaml at the repo root
worktree:
  sharedDirectories:
    - node_modules
    - .cache

# .worktreeinclude at the repo root
.env
.env.local
.vscode/settings.json

Portlar kendi kuralını hak eder. İki ajan aynı dev server’ı başlatırsa ikincisi başarısız olur ya da daha kötüsü birincinin veritabanına bağlanır. Portu ve veritabanı adını worktree başına bir ortam dosyasına koyun veya setup hook’un bunları worktree adından türetmesini sağlayın.

Diff’i inceleyin, sonra worktree’yi kaldırın

Her worktree’yi başladığı ref’e göre inceleyin, main üzerinde o an ne varsa ona göre değil. Bu, diff’i ajanın işine odaklı tutar. Nethür diff’i çalışma alanı başına gösterir, satır içi notları destekler ve commit’lemeden önce inceleme notlarını ajana geri gönderebilir. Böylece ajanın işi, maine sonradan eklenen değişikliklerle karışmaz.

İş merge edildiğinde worktree’yi ve branch’i kaldırın. Dizini elle silmeyin: git .git/worktrees altında metadata tutar ve elle rm -rf geride bayat bir kayıt bırakır.

git worktree remove ../app-fix-login
git branch -d fix/login

# if git refuses because the branch has unmerged commits
git worktree remove --force ../app-fix-login

Git, worktree gittikten sonra bile merge edilmemiş commit’ler içeren yerel bir branch’i tutabilir. Bu bir güvenlik ağıdır, hata değil. Nethür tutulan branch’leri bir inceleme adımında gösterir, böylece hangilerini zorla silmek istediğinize karar verirsiniz; sonradan peşlerine düşmeniz gerekmez.

Yaygın worktree hataları

  • Aynı branch’i iki worktree’de checkout etmek. Git reddeder; ikinci ajan için farklı bir branch seçin.
  • Worktree’yi repo içine koymak. Aramalar ve editörler yinelenen dosyalar görür ve dizin commit edilebilir.
  • Ana veritabanını işaret eden tek bir .env paylaşmak. Migration’lar söz konusuysa her ajan kendi veritabanını veya şemasını almalı.
  • Temel ref’i unutmak. Bayat bir yerel branch’ten oluşturulan worktree kafa karıştırıcı bir diff ve acı verici bir merge üretir.
  • Deneyden sonra onlarca worktree’yi açık bırakmak. Hangi branch’in kazandığını hâlâ hatırlarken branch’leri temizleyin.

Ekipte worktree’ler

Bir ekip sunucusunda worktree’ler artık özel dizinler değildir. Paylaşılan proje durumudur: bir ekip arkadaşı bir worktree’nin var olduğunu, kimin oluşturduğunu, hangi ajanın çalıştığını ve bloke olup olmadığını görebilir. İşi güvenle devretmeyi sağlayan bu görünürlüktür.

Nethür dizüstü bilgisayarınızda, bir ekip arkadaşınızın makinesinde, bir VPS’te veya bir SSH hedefinde çalışsa da aynı worktree modelini korur. Ajan checkout’un bulunduğu yerde çalışır ve istemci yalnızca oturumu render eder. Bu kurulumun ekip sürümünü istiyorsanız Ekipler için Claude Code yazısını okuyun.

Tek bir görevde deneyin

Küçük bir değişiklik için bir worktree oluşturun, içinde Claude Code başlatın ve ana checkout’unuzu yanında açık tutun. İki oturumun birbirine karışmayı bıraktığını gördüğünüzde ekstra dizin yük gibi gelmeyi bırakır. Paralel ajanlar rehberi bunu birkaç ajana nasıl ölçekleyeceğinizi ve sonuçlarını nasıl karşılaştıracağınızı gösterir.

Rehberi işe koşun.

Nethür’ü indirin ve ilk paralel ajanınızı dakikalar içinde çalıştırın; ya da zaten sahip olduğunuz bir makinede ekip çalışma alanı kurun.