Claude Code'da Git Worktree: Paralel Oturumları İzole Çalıştırma Rehberi

Q: Claude Code worktree'leri nerede oluşturur?

Varsayılan olarak depo kökünde .claude/worktrees/ / altında ve worktree- adlı yeni bir dalda. PR'dan açılan worktree'ler .claude/worktrees/pr- altına gider. Konumu değiştirmek için ya worktree'yi git worktree add ile kendiniz oluşturursunuz ya da bir WorktreeCreate hook'u yazarsınız.

Q: Worktree belirli bir daldan açılabilir mi?

worktree.baseRef yalnızca "fresh" (remote'taki varsayılan dal) ve "head" (yerel HEAD) değerlerini kabul eder, dal adı almaz. Var olan bir dal için git worktree add ../klasor dal-adi ile worktree'yi kendiniz oluşturup içinde claude çalıştırın. Bir pull request için ise claude --worktree "#1234" kullanabilirsiniz.

Q: Subagent'larımı worktree'de nasıl çalıştırırım?

Claude'a "ajanların için worktree kullan" diyebilir ya da .claude/agents/ altındaki subagent dosyasının frontmatter'ına isolation: worktree ekleyebilirsiniz. Her subagent geçici bir worktree alır; değişiklik yapmadan biterse worktree otomatik silinir, değişiklik varsa periyodik tarama iş kaybetmeden silebilene kadar kalır.

Claude Code ile bir süre çalıştıktan sonra herkes aynı noktaya geliyor: bir terminalde Claude yeni bir özellik yazarken, ikinci bir terminalde başka bir hatayı düzelttirmek istiyorsunuz. İki oturumu aynı klasörde açarsanız ikisi de aynı dosyalara yazar, biri diğerinin yarım kalmış değişikliğini görür, testler birbirine karışır ve hangi değişikliğin hangi göreve ait olduğu belirsizleşir. Claude Code'un bu soruna resmi cevabı git worktree desteği: claude --worktree bayrağı, EnterWorktree aracı, subagent'lar için isolation: worktree, .worktreeinclude dosyası ve worktree.* ayarları.

Bu yazıda Claude Code'da worktree kullanımını baştan sona anlatıyorum: worktree'nin ne olduğu, bir oturumu worktree içinde başlatma, ortamı hazırlama, oturumdan çıkarken temizlik kuralları, oturuma geri dönme, Claude Code'un izolasyonu nasıl zorladığı, subagent'ları worktree'de çalıştırma, temel dalı (base branch) seçme, pull request'ten worktree açma, büyük monorepo'lar için sparse checkout, git dışı sürüm kontrol sistemleri için hook'lar ve sık görülen hatalar. Bütün komut, ayar ve sürüm bilgileri Claude Code'un resmi dokümantasyonundan (code.claude.com/docs) alındı ve 19 Ekim 2026 itibarıyla kontrol edildi.

Git Worktree Nedir, Claude Code'da Neden Önemlidir?

Git worktree, aynı depoya bağlı ikinci (veya üçüncü, dördüncü...) bir çalışma klasörüdür. Her worktree'nin kendi dosyaları ve kendi dalı vardır, ama depo geçmişi ve remote'lar ana checkout ile ortaktır. Yani depoyu ikinci kez klonlamak yerine, aynı .git verisini paylaşan ayrı bir dosya kopyası elde edersiniz.

Claude Code açısından bunun anlamı basit: her oturumu kendi worktree'sinde çalıştırırsanız her oturum düzenleyeceği dosyaların ayrı bir kopyasına sahip olur. Böylece bir oturum özellik geliştirirken ikincisi hata düzeltebilir ve değişiklikler çakışmaz. Dokümantasyon worktree'leri Claude'u paralel çalıştırmanın birkaç yolundan biri olarak konumluyor ve rollerini şöyle ayırıyor:

Worktree'ler dosya düzenlemelerini izole eder; her oturum dosyaların ayrı bir kopyasını düzenler.
Subagent'lar tek bir oturumun içinde işi böler; yan görevi kendi bağlamında yapıp özet döndürür.
Cross-session messaging, farklı worktree'lerdeki oturumların bulgularını birbirine aktarmasını sağlar.
Agent view, arka planda çalışan oturumları tek ekrandan başlatıp izlemenizi sağlar; buradan başlatılan bir oturum dosya düzenlemeden önce kendi worktree'sine geçer.
/batch, büyük bir değişikliği 5 ila 30 arası worktree'de izole subagent'a bölen paketlenmiş bir skill'dir.

Dokümantasyondaki karar sorusu da net: "Görevler aynı dosyalara dokunuyor mu?" Cevap evetse işi worktree'lerle izole edin. Agent teams özelliği ise ekip üyelerini worktree'lerde izole etmez; orada işi her üye farklı dosya setine sahip olacak şekilde bölmeniz gerekir. Subagent'ların temellerini Claude Code subagent rehberinde, arka plan oturumlarını Agent View rehberinde ayrıntılı anlattım.

Claude Code'u Worktree İçinde Nasıl Başlatırım?

En kısa yol --worktree (kısaca -w) bayrağına bir isim vermek. Claude Code varsayılan olarak worktree'yi depo kökünde .claude/worktrees/<isim>/ altında, worktree-<isim> adında yeni bir dalda oluşturur ve oturumu orada açar:

# .claude/worktrees/feature-auth/ altında, worktree-feature-auth dalında
claude --worktree feature-auth

# Kısa hali; ikinci bir terminalde ikinci izole oturum
claude -w bugfix-123

# İsim vermezseniz Claude Code bright-running-fox gibi bir isim üretir
claude --worktree

Aynı komutu başka bir terminalde farklı bir isimle çalıştırdığınızda ikinci, tamamen izole bir oturum başlar. Birkaç önemli ayrıntı var:

Workspace trust: Etkileşimli çalıştırmalar çalışma alanı güvenini gerektirir. Claude'u o klasörde daha önce hiç çalıştırmadıysanız önce bir kez claude çalıştırıp güven diyalogunu kabul edin; aksi halde --worktree bunu isteyen bir hatayla çıkar. -p ile yapılan etkileşimsiz çalıştırmalar güven kontrolünü atlar, yani claude -p --worktree doğrudan çalışır.
En az bir commit: Worktree mevcut bir commit'ten oluşturulduğu için deponun en az bir commit'i olmalı. Hiç commit'i olmayan bir depoda komut Failed to resolve base branch "HEAD": git rev-parse failed hatasıyla başarısız olur.
.gitignore: Dokümantasyon .claude/worktrees/ klasörünü .gitignore'a eklemenizi öneriyor; böylece worktree içerikleri ana checkout'ta izlenmeyen dosyalar olarak görünmez.

echo ".claude/worktrees/" >> .gitignore

Worktree'leri tmux ile açmak

Paralel oturumları ayrı terminal sekmelerinde yönetmek yerine --tmux bayrağını kullanabilirsiniz. Bu bayrak worktree için bir tmux oturumu oluşturur ve --worktree gerektirir. iTerm2'nin yerel bölmeleri varsa onları kullanır; klasik tmux için --tmux=classic verilir:

claude -w feature-auth --tmux
claude -w feature-auth --tmux=classic

Oturum içinden worktree istemek

Worktree'yi baştan açmak zorunda değilsiniz. Oturum sırasında Claude'a "bir worktree'de çalış" demeniz yeterli; Claude bunu EnterWorktree aracıyla oluşturur ve içine geçer. Bir worktree içindeyken .claude/worktrees/ altındaki başka bir worktree'ye de doğrudan geçebilir; önceki worktree diskte dokunulmadan kalır.

Claude deponun .claude/worktrees/ klasörü dışındaki bir yola girmek istediğinde Claude Code önce onayınızı ister, çünkü bu geçiş oturumun çalışma dizinini, yazma erişimini ve CLAUDE.md ile ayarlar gibi proje yapılandırmasını o konuma taşır. Bir EnterWorktree izin kuralı veya "don't ask again" seçimi bu istemi kapatmaz; yalnızca bypassPermissions modu atlar. v2.1.206 öncesinde Claude var olan herhangi bir worktree yoluna sormadan girebiliyordu.

Worktree Ortamını Hazırlamak: .worktreeinclude ve Bağımlılıklar

Worktree temiz bir checkout'tur. Bu, ana klasörünüzde olan ama git'in izlemediği dosyaların yeni worktree'de olmayacağı anlamına gelir: .env, .env.local, yerel gizli anahtar dosyaları, kurulmuş bağımlılıklar. Bağımlılıklar için Claude'dan kurulum yapmasını isteyebilir ya da projenizin kurulum komutunu .claude/worktrees/ altındaki worktree klasöründe kendiniz çalıştırabilirsiniz.

Gitignore'daki dosyaları her yeni worktree'ye otomatik taşımak için proje köküne bir .worktreeinclude dosyası eklenir. Dosya .gitignore söz dizimini kullanır. Yalnızca bir desene uyan ve aynı zamanda gitignore'da olan dosyalar kopyalanır; bu sayede izlenen dosyalar asla çiftlenmez:

# .worktreeinclude
.env
.env.local
config/secrets.json

Bu dosya Claude Code'un git ile oluşturduğu bütün worktree'lere uygulanır: --worktree worktree'leri, subagent worktree'leri ve masaüstü uygulamasındaki paralel oturumlar. Bir WorktreeCreate hook'u kullanıyorsanız .worktreeinclude işlenmez; dosyaları hook betiğinin içinde kopyalamanız gerekir.

**/ ile başlayan desenlerde bir incelik var: istediğiniz dosyalar bütünüyle gitignore'da olan bir klasörün içindeyse, Claude Code onları ancak o klasörün kendisi desene uyuyorsa ya da **/ sonrasındaki ilk isim klasörün yolundaki isimlerden biriyse kopyalar. Örneğin **/.claude/skills/*.md yazarsanız ilk isim .claude olduğu için yok sayılan .claude/ klasöründen eşleşen dosyalar kopyalanır. Bir **/ deseninin ulaşamadığı yok sayılmış bir klasör için klasörü desende açıkça yazın: **/config.json yerine vendor/**/config.json. Bu davranış v2.1.239 ile genişletildi.

node_modules'u çiftlememek: symlinkDirectories

Her worktree'ye node_modules gibi büyük bir klasörü yeniden kurmak disk ve zaman maliyetlidir. worktree.symlinkDirectories ayarı, listelenen klasörleri ana depodan her worktree'ye sembolik bağlantı olarak bağlar. Yollar depo köküne görelidir ve varsayılan olarak hiçbir klasör bağlanmaz:

{
  "worktree": {
    "symlinkDirectories": ["node_modules", ".cache"]
  }
}

Burada pratik bir uyarı eklemek gerekiyor: sembolik bağlantı, bütün worktree'lerin aynı node_modules klasörünü paylaşması demek. Bir oturumda bağımlılık sürümü değiştiren bir iş yapıyorsanız (örneğin bir paketi yükseltiyorsanız) o değişiklik diğer worktree'leri de etkiler. Bu tür görevlerde o klasörü bağlamak yerine worktree'de ayrı kurulum yapmak daha güvenli.

Worktree'den Çıkınca Ne Olur? Temizlik Kuralları

Etkileşimli bir worktree oturumundan çıktığınızda Claude Code, worktree silinirse kaybolacak iş olup olmadığını kontrol eder: değiştirilmiş veya izlenmeyen dosyalar, checkout edilmiş submodule'lerdeki commit edilmemiş işler ve yeni commit'ler. Sonuca göre üç davranış var:

Durum	Claude Code ne yapar?
Worktree temiz, oturum isimsiz	Worktree'yi ve dalını otomatik siler.
Worktree temiz, oturum isimli	Daha sonra kullanmak isteyebileceğiniz için önce sorar.
Worktree'de iş var	Tutmak mı silmek mi istediğinizi sorar. Tutarsanız klasör ve dal korunur; çıkışta yazdırılan `claude --worktree <isim> --resume` komutuyla geri dönersiniz. Silerseniz klasör, dal ve içindeki bütün iş gider.
Durum doğrulanamıyor	Değişiklikleri sayamıyor ya da submodule'leri inceleyemiyorsa otomatik silmez, sorar; istemde neyi kontrol edemediğini belirtir.

-p ile yapılan etkileşimsiz çalıştırmalarda çıkış istemi olmadığı için Claude Code bu worktree'leri temizlemez ve oluşturma sırasında aldığı kilidi, daha sonraki bir oturumun eski kilit taraması (stale-lock sweep) serbest bırakana kadar yerinde bırakır. Böyle bir worktree'yi kaldırmak için git worktree remove kullanılır; git worktree kilitli olduğu için reddederse önce git worktree unlock çalıştırılır:

git worktree list
git worktree unlock .claude/worktrees/feature-auth
git worktree remove .claude/worktrees/feature-auth
# Commit edilmemiş değişiklik veya izlenmeyen dosya varsa
git worktree remove --force .claude/worktrees/feature-auth

Windows kullanıcıları için bir güvence: worktree silindiğinde worktree dışındaki dosyalar silinmez. Worktree içindeki bir klasör NTFS junction veya dizin sembolik bağlantısıysa Claude Code yalnızca bağlantıyı siler, işaret ettiği klasörü korur. v2.1.205 öncesinde alt klasöre yerleştirilmiş bir bağlantı içeren worktree silindiğinde işaret edilen klasör de silinebiliyordu; eski bir sürümdeyseniz claude update ile güncellemeniz iyi olur.

Subagent ve arka plan oturumu worktree'leri nasıl temizlenir?

Claude Code, subagent'lar ve arka plan oturumları için oluşturduğu worktree'leri periyodik bir taramayla siler; eşik cleanupPeriodDays ayarıdır (varsayılan 30 gün). Bir --worktree oturumunu arka plana gönderdiğinizde onun worktree'si de bu taramanın kapsamına girer. Tarama şu durumlarda worktree'yi yerinde bırakır:

Worktree'de hâlâ iş varsa: değiştirilmiş veya izlenmeyen dosyalar ya da push edilmemiş commit'ler.
Checkout edilmiş bir submodule'de değişmiş veya izlenmeyen dosyalar varsa ya da Claude Code submodule'leri inceleyemiyorsa (v2.1.274 ve üstü).
Claude Code deponun yapılandırmasında hangi filter driver'ların tanımlı olduğunu belirleyemiyor ya da kapatamadığı bir ayar buluyorsa.
Worktree arka plana göndermediğiniz bir --worktree oturumuna aitse, yaşı ne olursa olsun.
Worktree'yi kendiniz git worktree add ile oluşturduysanız.

Claude Code git ile oluşturduğu her worktree'nin git meta verisine bir işaret yazar ve tarama bu işareti taşımayan her worktree'yi korur. Bir ajan çalışırken worktree'si üzerinde git worktree lock tutulur ve ajan bitince kilit bırakılır. Süreci sonlanmış bir oturumun kilidini de tarama serbest bırakır, ama sizin elle koyduğunuz kilide asla dokunmaz. v2.1.210 öncesinde öldürülen bir oturumun bıraktığı kilit, siz git worktree unlock çalıştırana kadar kalıyordu.

Worktree Oturumuna Nasıl Geri Dönerim?

Worktree içinde biten bir oturumu (worktree'den çıkmadan) devam ettirdiğinizde Claude Code oturumu o worktree'ye geri götürür. Bu kural etkileşimli devam ettirmeler, -p ile etkileşimsiz moddaki --continue ve --resume ve Agent SDK için geçerli. --continue, başlattığınız klasör altında kaydedilmiş en son oturumu seçer. Worktree'ye döndükten sonra Claude isterse ExitWorktree aracıyla worktree'den çıkabilir.

# Çıkışta yazdırılan komutla isimli worktree'ye dönüş
claude --worktree feature-auth --resume

# Ana checkout'tan bir oturumu isim veya ID ile devam ettirme
claude --resume auth-refactor

Hangi davranışı göreceğiniz nereden başlattığınıza ve nasıl devam ettirdiğinize bağlı:

Başlatma klasörü: --resume'u ana checkout'tan veya deponun başka bir klasöründen çalıştırın. Claude Code, .claude/worktrees/ altında git ile kendi oluşturduğu bir worktree'ye, onun içinden başlatsanız bile tekrar girer. Başka bir worktree'nin içinden başlattığınızda ise ancak oradan kefil olabiliyorsa girer; kendi başına depo olan, git meta verisi olmayan veya git worktree add ile oluşturduğunuz bir worktree'nin alt klasöründen başlatılan durumlar reddedilir. Bunları ana checkout'tan başlatın.
--fork-session: Çatallanan oturum Claude'u başlattığınız klasörde açılır ve orijinal oturumun worktree'sine dokunulmaz.
Silinmiş worktree: Worktree klasörü artık yoksa oturum başlattığınız klasörde devam eder; Claude Code worktree'nin gittiğini söyler ve oturumun worktree bağını temizler.

Claude git ile oluşturulmuş bir worktree'ye girip çıktığında oturum kaydı (transcript) da onu takip eder; oturum yeni çalışma dizini altında kaydedilir, böylece /desktop ve --resume onu orada bulur. Bu davranış v2.1.198 veya üstünü gerektirir. --resume'a bir oturum ID'si verdiğinizde Claude Code önce mevcut proje klasörünü ve onun git worktree'lerini, ardından makinedeki diğer projeleri arar.

Claude Code Worktree İzolasyonunu Nasıl Zorlar?

Worktree'nin asıl değeri, oturumun ana checkout'a gerçekten dokunamamasında. Bir oturum worktree'de izoleyken Claude Code belirli araç çağrılarını engeller. Kurallar oturumu --worktree ile başlatmanız, Claude'un EnterWorktree ile girmesi veya bir worktree oturumunu devam ettirmeniz fark etmeksizin aynıdır ve izole oturumdan doğan her subagent'ı da kapsar. Dört kontrol var:

Dosya düzenlemeleri: Ana checkout'taki bir yolu hedefleyen Edit, Write veya NotebookEdit engellenir.
Komut çalışma dizini: Çalışma dizini ana checkout'a çözümlenen ya da dışarıda kaldığı doğrulanamayan Bash, PowerShell veya Monitor komutu engellenir.
Git yönlendirmeleri: Git'i ana checkout'a yönlendiren Bash veya Monitor komutu engellenir. Yönlendirme git -C, --git-dir, GIT_DIR veya GIT_WORK_TREE değişkeni ya da git'ten önce ana checkout'a cd ile gelebilir.
Komut biçimi: Komut metninden, çalıştırdığı git'in worktree içinde kaldığı doğrulanamıyorsa komut engellenir; örneğin komut adı çalışma anında hesaplanıyorsa, söz dizimi ayrıştırılamıyorsa ya da ${!name} gibi bir genişletme metinde yazmayan bir komut çalıştırabiliyorsa. Claude Code reddedilen komutun nasıl yeniden yazılacağını (örneğin düz, ayrı komutlara bölmeyi) Claude'a söyler. Bu kontrol kapatılamaz.

Sınırı bilmek önemli: bu kontroller düzenlemenin hedeflediği yolu, komutun çalıştığı dizini ve komut metnini okur. Hiçbiri bir kabuk komutunun hangi dosyalara yazdığını takip etmez. Dolayısıyla git çalıştırmadan ana checkout'a yazan cp veya bir kabuk yönlendirmesi bu kontrollerce reddedilmez; o komut diğer kabuk komutları gibi izin ve sandbox ayarlarınıza tabidir. Bu yüzden worktree izolasyonunu bir güvenlik sınırı olarak değil, kazara çakışmayı önleyen bir mekanizma olarak düşünmek ve gerçek kısıtlama için izin kuralları ile sandbox'ı birlikte kullanmak gerekiyor. PowerShell komutlarında yalnızca çalışma dizini kontrolü uygulanır.

Hook'lar worktree'yi takip eder mi?

Claude bir worktree'ye girdikten sonra hook'larınızdaki ${CLAUDE_PROJECT_DIR} yerinde kalır; hâlâ oturumun başladığı proje kökünü gösterir. Yani ${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh gibi bir hook komutu betiği ana checkout'tan çalıştırır. Worktree yolu hook'a başka bir yoldan gelir: hook'un girdi JSON'undaki cwd alanı worktree köküdür ve Claude cd çalıştırdıkça değişir. Worktree'deki dosyalar üzerinde çalışması gereken bir hook (örneğin formatlayıcı) bu alanı, örneğin jq -r '.cwd' ile okumalı. Hook yapısını Claude Code hooks rehberinde anlattım.

Subagent'ları Worktree'de Çalıştırmak: isolation: worktree

Paralel çalışan subagent'lar aynı dosyalara yazarsa aynı çakışma sorunu subagent seviyesinde ortaya çıkar. Çözüm iki türlü: Claude'a "ajanların için worktree kullan" demek ya da özel bir subagent'ın frontmatter'ına isolation: worktree ekleyerek izolasyonu kalıcı yapmak. Aşağıdaki .claude/agents/refactorer.md her zaman kendi worktree'sinde çalışır:

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---

Apply the requested refactor across every affected file, then run the tests
and report the results.

Her subagent geçici bir worktree alır. Subagent değişiklik yapmadan biterse Claude Code worktree'yi otomatik siler; değişiklik içeren bir worktree ise yukarıda anlattığım periyodik tarama iş kaybetmeden silebilene kadar diskte kalır. Subagent worktree'leri --worktree ile aynı temel dalı kullanır, yani worktree.baseRef "head" yapılmadıkça deponun varsayılan dalından açılır.

Gözden kaçabilecek bir davranış: kendi worktree'sindeki bir subagent, başlangıçta yüklediği talimat dosyalarını worktree'den değil ana konuşmanızdan alır. Worktree varsayılan konumda (.claude/worktrees/) ise subagent oradaki dosyaları okurken worktree kökündeki CLAUDE.md dosyasını veya .claude/rules/ klasörünü de yüklemez; worktree'nin dalında bunlar farklı olsa bile. Yani bir dalda CLAUDE.md'yi değiştirip subagent'ın o yeni kurallarla çalışmasını bekliyorsanız beklentiniz karşılanmaz.

/batch: büyük değişiklikleri paralel worktree'lere bölmek

/batch <talimat>, kod tabanı geneline yayılan büyük değişiklikler için paketlenmiş bir skill. Kod tabanını araştırır, işi 5 ila 30 bağımsız birime böler ve bir plan sunar. Onayladığınızda her birim için izole bir worktree'de çalışan bir arka plan subagent'ı başlatır; her subagent kendi birimini uygular, testleri çalıştırır ve değişikliğini yayımlar. Bir git deposu ya da worktree'leri oluşturan bir WorktreeCreate hook'u gerektirir; git deposu dışında kullanım v2.1.281 veya üstünü ister.

/batch migrate src/ from JavaScript to TypeScript

Worktree Hangi Daldan Açılır? worktree.baseRef

Yeni worktree'ler varsayılan olarak deponun varsayılan dalından açılır. Bu davranışı worktree.baseRef ayarı belirler ve iki değer kabul eder:

Değer	Davranış	Ne zaman?
`"fresh"` (varsayılan)	Remote'taki varsayılan daldan (`origin/<default-branch>`, genelde `main`) açılır; worktree remote ile eşleşen temiz bir ağaçla başlar.	Birbirinden bağımsız yeni görevler, hata düzeltmeleri, push edilmemiş işinizin yeni göreve sızmasını istemediğiniz durumlar.
`"head"`	Yerel `HEAD`'inizden açılır; push edilmemiş commit'ler ve özellik dalının durumu worktree'de bulunur. Bir worktree içindeyken o worktree'nin `HEAD`'ine çözülür.	Devam eden bir iş üzerinde çalışması gereken subagent'ları izole ederken.

{
  "worktree": {
    "baseRef": "head"
  }
}

worktree.baseRef'e bir dal adı veremezsiniz. Belirli, var olan bir daldan worktree başlatmak için worktree'yi doğrudan git ile oluşturmanız gerekir (aşağıda göstereceğim). "fresh" tabanında Claude Code origin/HEAD'i güncel tutar: depo son 24 saatte fetch edilmediyse varsayılan dalı en fazla beş saniyelik bir sınırla fetch eder, başarısız olursa yerelde önbelleklenmiş referansı kullanır. Bu fetch terminalde asla girdi beklemez; git veya ssh parola, anahtar parolası ya da yeni bir SSH host onayı isterse fetch başarısız sayılır. Remote tanımlı değilse veya origin/HEAD yerelde yoksa ve fetch edilemiyorsa worktree yerel HEAD'den açılır. Bu ayar, Claude Code'un 2026'nın 19. haftası sürüm notlarında duyuruldu.

Aynı worktree adını tekrar kullanmak

--worktree'e klasörü zaten var olan bir isim verirseniz Claude Code yeni bir worktree oluşturmak yerine mevcut olanı açar. Varsayılan "fresh" tabanında, şu koşulların hepsi sağlanıyorsa yeniden açılan worktree eski ucunda devam etmek yerine varsayılan dala sıfırlanır: commit edilmemiş değişiklik veya izlenmeyen dosya yoksa, hâlâ Claude Code'un oluşturduğu daldaysa ve kendine ait commit'i yoksa ya da pull request'i birleştirilip remote dalı silindiyse. baseRef "head" ise, isim bir PR referansıysa ya da durum doğrulanamıyorsa worktree eski ucunda açılır.

Pull Request'ten Worktree Açmak

Bir pull request'i incelemek veya üzerinde çalışmak için --worktree'e başına # konmuş PR numarasını, bir GitHub pull request URL'sini ya da bir GitLab merge request URL'sini verebilirsiniz. Claude Code o değişikliğin head commit'ini origin'den fetch eder ve worktree'yi .claude/worktrees/pr-<numara> altında oluşturur. Kabuğun #'i yorum başlangıcı saymaması için argümanı tırnak içine alın:

claude --worktree "#1234"
claude -w https://gitlab.com/group/repo/-/merge_requests/123

Claude Code URL'den yalnızca numarayı okur ve her zaman origin remote'undan fetch eder. github.com'da pull/<numara>/head, gitlab.com'da merge-requests/<numara>/head fetch edilir; GitHub Enterprise, self-managed GitLab veya başka bir host'ta önce birincisi, sonra ikincisi denenir. Bu fetch de girdi beklemez; kimlik doğrulama isteniyorsa Error creating worktree: Failed to fetch PR/MR #<numara> hatasıyla çıkar. ssh-agent'ta tutulan bir anahtar çalışır; bu yüzden anahtarınızı oraya yükleyin ve yeni bir host'u kaydetmek için başlamadan önce bir kez elle git fetch çalıştırın. GitLab merge request desteği v2.1.233 ile geldi.

Büyük Monorepo'larda Sparse Worktree: worktree.sparsePaths

--worktree varsayılan olarak bütün depoyu checkout eder. Büyük bir depoda bu hem yavaş hem de disk açısından pahalı. worktree.sparsePaths ayarı git sparse-checkout kullanarak yalnızca listelenen klasörleri ve kök seviyesindeki dosyaları diske yazar; worktree'ler daha hızlı başlar ve daha az yer kaplar.

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ],
    "symlinkDirectories": [
      "node_modules"
    ]
  }
}

Bu yapılandırmayla Claude bir worktree oluşturduğunda tüm ağaç yerine yalnızca .claude/, packages/api/ ve packages/shared/ checkout edilir; node_modules ise ana depodaki kopyaya sembolik bağlantı olur. Dikkat edilmesi gerekenler:

sparsePaths içindeki yollar, Claude'u hangi alt klasörden başlatırsanız başlatın depo köküne göredir.
Tek tek dosyaları değil klasörleri listeleyin. package.json, tsconfig.base.json ve lock dosyaları gibi kök seviyesindeki dosyalar her zaman checkout edilir; kök seviyesindeki klasörler edilmez. Kökteki .claude/settings.json veya .claude/rules/ worktree'de lazımsa listeye .claude ekleyin.
Bir oturumdaki bütün worktree'ler aynı sparsePaths'i paylaşır. Bir subagent packages/api/, diğeri packages/web/ istiyorsa ikisini de listeleyin.
Ekipçe aynı yollar gerekiyorsa ayarı .claude/settings.json'a commit edin; kendinize yol eklemek için .claude/settings.local.json kullanın. Listeler kapsamlar arasında birleşir; yerel dosya yol ekleyebilir ama çıkaramaz.
Sparse bir worktree varken git, deponun paylaşılan .git/config dosyasında extensions.worktreeConfig'i etkinleştirir. Claude Code bu girdiyi son worktree silindikten sonra, yalnızca kendisi eklediyse kaldırır.

Worktree Ana Checkout ile Neleri Paylaşır?

Worktree'nin kendi dosyaları ve dalı vardır ama bazı şeyler ana checkout ile ortaktır. Bunlar hem --worktree ile hem de git worktree add ile oluşturulan worktree'ler için geçerli:

Paylaşılan	Ayrıntı
Deponun `.git` klasörü	Worktree'deki git komutları ana deponun ortak `.git` klasörüne yazar; sandbox bu yazmalara izin verir, böylece sandbox açıkken de `git commit` çalışır.
Plugin'ler	Ana checkout'tan proje kapsamında kurulan plugin'ler aynı deponun worktree'lerinde de yüklenir; worktree başına yeniden kurmanız gerekmez (v2.1.200+).
İzin onayları	Worktree oturumunda bir Bash komutu için "Yes, and don't ask again" seçerseniz kural ana checkout'un `.claude/settings.local.json` dosyasına kaydedilir; ana checkout'ta ve diğer worktree'lerde geçerli olur, worktree silinse de kalır (v2.1.211+). Windows'ta ve depo kökünün kullanılmadığı diğer durumlarda kural o worktree'de kalır.
İzlenmeyen skill, agent ve komutlar	Worktree checkout'unun kökünde `.claude/skills` klasörü yoksa (örneğin gitignore'da olduğu için) ana checkout'un proje skill'leri yüklenir. Aynı okuma `.claude/agents` ve `.claude/commands` için de geçerli. Skill'ler için v2.1.277 gerekir.

Masaüstü uygulamasından başlatılan worktree oturumlarında durum biraz farklı: ayarlar, hook'lar, skill'ler, agent'lar, komutlar ve .mcp.json sunucuları gibi proje yapılandırması worktree'den değil ana checkout'un kökünden okunur; hook komutları o kökte çalışır. CLAUDE.md dosyaları ve .claude/rules/ ise yine worktree'den yüklenir. Masaüstü uygulamasındaki paralel oturumlar için Claude Code Desktop rehberine bakabilirsiniz.

Worktree'leri Git ile Elle Yönetmek

Var olan belirli bir dalı checkout etmeniz ya da worktree'yi deponun dışına koymanız gerekiyorsa worktree'yi doğrudan git ile oluşturup Claude'u içinde başlatabilirsiniz:

# Yeni dalda worktree
git worktree add ../project-feature-a -b feature-a

# Var olan bir daldan worktree
git worktree add ../project-bugfix fix-issue-456

# Claude'u worktree içinde başlat
cd ../project-feature-a
claude

# Worktree'leri listele ve işi bitince kaldır
git worktree list
git worktree remove ../project-feature-a

Bir not: Claude git worktree add'i EnterWorktree yerine Bash aracıyla çalıştırırsa WorktreeCreate hook'unuz tetiklenmez. O komutu incelemek veya engellemek için Bash matcher'ına sahip bir PreToolUse hook'u eklemeniz gerekir. Ayrıca elle oluşturduğunuz worktree'ler Claude Code'un işaretini taşımadığı için periyodik tarama tarafından asla silinmez; temizlik sizin sorumluluğunuzda.

Git Dışı Sürüm Kontrolü: WorktreeCreate ve WorktreeRemove Hook'ları

Worktree izolasyonu varsayılan olarak git kullanır. SVN, Perforce, Mercurial veya başka sistemler için WorktreeCreate ve WorktreeRemove hook'larıyla oluşturma ve temizleme mantığını kendiniz sağlarsınız. Hook varsayılan git davranışının tamamen yerini aldığı için .worktreeinclude işlenmez.

WorktreeCreate; claude --worktree, EnterWorktree, isolation: "worktree" kullanan subagent'lar, kendi worktree'sinde ajan çalıştıran workflow'lar, arka plan oturumlarının izolasyonu ve worktree modundaki claude remote-control durumlarında çalışır. Hook, ortak alanlara ek olarak stdin'deki JSON'da bir name alanı alır (örneğin feature-auth) ve oluşturduğu klasörün yolunu döndürmek zorundadır. Command hook'larında yol stdout'un son boş olmayan satırı olarak yazdırılır, diğer çıktılar stderr'e yönlendirilmelidir:

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ],
    "WorktreeRemove": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'jq -r .worktree_path | xargs rm -rf'"
          }
        ]
      }
    ]
  }
}

HTTP hook'ları ise yanıt gövdesinde { "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } } döndürür. Hook başarısız olursa veya yol üretmezse worktree oluşturma hatayla sonuçlanır. Claude Code . veya .. parçaları içeren mutlak yolları ve depo kökünün altında bir sembolik bağlantıdan geçen her yolu reddeder.

WorktreeRemove tarafında bilmeniz gerekenler: hook 0 ile çıkarsa worktree silinmiş sayılır ve Claude Code başka bir şey okumaz, yani klasörü gerçekten sildiğinizden emin olun. Claude Code değişiklikleri git ile aradığı için git checkout'u olmayan bir klasörde commit edilmemiş iş olsa bile hiçbir şey bulamaz; silmeden önce o kontrolü hook'unuzun içinde yapmalısınız. Bir subagent veya workflow ajanı bittiğinde Claude Code hook'unuzun oluşturduğu worktree'yi tutar ve WorktreeRemove'u çalıştırmaz; bunları işiniz bitince kendiniz silmelisiniz. Hook'unuz bir dal oluşturuyorsa onu da WorktreeRemove'da silin, çünkü Claude Code yalnızca yolu bildiği için o dala dokunmaz. Hook'un ayrıca bir uyarısı var: klasörleri herhangi bir deponun dışında oluşturun. Hook klasörü bir deponun içinde oluşturursa git onu o deponun checkout'una çözer ve Claude Code worktree'yi reddeder.

Gerçek Bir İş Akışı: Bir Özellik, Bir Hata ve Bir PR İncelemesi

Yukarıdaki parçaları birleştiren, Node.js tabanlı bir proje için uçtan uca bir senaryo düşünelim. Hedef: bir terminalde ödeme sayfasına yeni bir özellik eklemek, ikincisinde üretimdeki bir hatayı düzeltmek, üçüncüsünde bir arkadaşınızın PR'ını incelemek.

1. Depoyu bir kez hazırlayın. .gitignore'a worktree klasörünü, kök dizine .worktreeinclude'u ekleyin ve .claude/settings.json'da node_modules'u sembolik bağlantı yapın:

echo ".claude/worktrees/" >> .gitignore
printf ".env\n.env.local\n" > .worktreeinclude

# .claude/settings.json
{
  "worktree": {
    "symlinkDirectories": ["node_modules"]
  }
}

2. Paralel oturumları başlatın. Her terminalde ayrı isimle:

# Terminal 1 — yeni özellik
claude -w checkout-kupon

# Terminal 2 — üretim hatası
claude -w hata-odeme-timeout

# Terminal 3 — PR incelemesi
claude -w "#482"

Üç oturum da origin/main'den (PR oturumu ise PR'ın head commit'inden) açılır; .env dosyaları kopyalanmış, node_modules bağlanmış olarak gelir. Biri diğerinin dosyalarına yazamaz; ana checkout'a yönelen bir Edit veya git -C komutu reddedilir.

3. Oturumlar arasında bilgi aktarın. Hata düzeltme oturumu, kupon özelliğinin de dokunduğu bir fonksiyonda sorun bulursa bu bulguyu diğer oturuma iletebilir; bunu sağlayan mekanizmayı cross-session messaging rehberinde anlattım.

4. Bitirin ve temizleyin. Hata düzeltmesi commit edilip push edildikten sonra oturumdan çıktığınızda Claude Code worktree'de iş olduğunu (yeni commit) görür ve tutmak ya da silmek isteyip istemediğinizi sorar. PR incelemesinde hiçbir değişiklik yapmadıysanız ve oturum isimsizse worktree ve dalı otomatik silinir. Yarım kalan kupon özelliğini tutarsınız ve ertesi gün çıkışta yazdırılan komutla devam edersiniz:

claude --worktree checkout-kupon --resume

Sık Karşılaşılan Hatalar ve Çözümleri

Failed to resolve base branch "HEAD": git rev-parse failed: Depoda hiç commit yok. İlk commit'i atın ve tekrar deneyin.
Worktree oluşturma sembolik bağlantılı yolda başarısız: .claude, .claude/worktrees veya worktree klasörünün kendisi bir symlink ise Claude Code reddeder ve hata symlink'li yolu söyler. Symlink'i kaldırıp tekrar deneyin.
Git LFS dosyaları worktree'de pointer dosyası olarak görünüyor: Git LFS'i git lfs install --local ile kurduysanız LFS filtresi deponun kendi .git/config'ine yazılır ve Claude Code worktree oluştururken deponun kendi filter driver'larını güvenlik nedeniyle atlar (v2.1.247'den beri). Gerçek dosyalar için worktree içinde git lfs pull çalıştırın. Global git lfs install bu durumdan etkilenmez.
The repository git config has a conditional include (includeIf): .git/config'teki includeIf'in çektiği ayarları doğrudan o dosyaya taşıyın ve includeIf'i kaldırın. Global git config'inizdeki bir includeIf bu hatayı tetiklemez.
Refusing to use <path> as an isolation worktree: Klasörün git meta verisi ana checkout'a çözülüyor (örneğin .git dosyası ana deponun kendi .git klasörünü gösteriyor ya da bir core.worktree yönlendirmesi var). Mesaj "launch from the parent checkout" diyorsa Claude Code'u worktree'nin içinden başlatmışsınızdır; ana checkout'tan başlatın.
Oturum worktree dışında devam ediyor: Your worktree <path> no longer exists mesajı worktree silindiği için gelir ve işlem gerekmez. Could not verify your worktree <path> this time genelde geçici bir nedenle olur; tekrar devam ettirmeyi deneyin.
Kilitli worktree silinmiyor: Önce git worktree unlock <yol>, sonra git worktree remove <yol>; commit edilmemiş değişiklik varsa --force ekleyin.

Otomasyonda (-p ve Agent SDK) Claude Code, silinmiş worktree dışındaki her ret durumunda devam ettirmeyi stderr hatasıyla durdurur. --output-format stream-json ile ret nedeni stdout'ta error_during_execution alt tipli bir result mesajı olarak da gelir ve startup_failure_reason alanı worktree_unverified veya worktree_resume_refused değerini taşır (v2.1.274+). Uygulamanız hata metnini eşleştirmek yerine bu alana göre dallanabilir.

Sıkça Sorulan Sorular

Claude Code worktree'leri nerede oluşturur?

Varsayılan olarak depo kökünde .claude/worktrees/<isim>/ altında ve worktree-<isim> adlı yeni bir dalda. PR'dan açılan worktree'ler .claude/worktrees/pr-<numara> altına gider. Konumu değiştirmek için ya worktree'yi git worktree add ile kendiniz oluşturursunuz ya da bir WorktreeCreate hook'u yazarsınız.

.env dosyam worktree'de neden yok?

Worktree temiz bir checkout olduğu için git'in izlemediği dosyalar gelmez. Proje köküne .gitignore söz dizimiyle bir .worktreeinclude dosyası ekleyip .env gibi dosyaları listeleyin; yalnızca hem desene uyan hem de gitignore'da olan dosyalar kopyalanır. WorktreeCreate hook'u kullanıyorsanız kopyalamayı hook betiğinde yapmalısınız.

Worktree'den çıktığımda yaptığım değişiklikler silinir mi?

Kendiliğinden silinmez. Worktree'de değişmiş veya izlenmeyen dosya ya da yeni commit varsa Claude Code tutmak mı silmek mi istediğinizi sorar. Yalnızca temiz bir worktree'yi, oturum isimsizse otomatik siler. -p ile yapılan etkileşimsiz çalıştırmalarda hiç temizlik yapılmaz; o worktree'leri git worktree remove ile kendiniz kaldırırsınız.

Worktree belirli bir daldan açılabilir mi?

worktree.baseRef yalnızca "fresh" (remote'taki varsayılan dal) ve "head" (yerel HEAD) değerlerini kabul eder, dal adı almaz. Var olan bir dal için git worktree add ../klasor dal-adi ile worktree'yi kendiniz oluşturup içinde claude çalıştırın. Bir pull request için ise claude --worktree "#1234" kullanabilirsiniz.

Worktree izolasyonu bir güvenlik sınırı mı?

Tam olarak değil. Claude Code ana checkout'u hedefleyen dosya düzenlemelerini, ana checkout'ta çalışan komutları ve git yönlendirmelerini engeller; ancak git çalıştırmadan ana checkout'a yazan cp veya bir kabuk yönlendirmesini bu kontroller yakalamaz. Böyle komutlar normal izin ve sandbox ayarlarınıza tabidir. Gerçek kısıtlama için worktree'yi izin kuralları ve sandbox ile birlikte kullanın.

Subagent'larımı worktree'de nasıl çalıştırırım?

Claude'a "ajanların için worktree kullan" diyebilir ya da .claude/agents/ altındaki subagent dosyasının frontmatter'ına isolation: worktree ekleyebilirsiniz. Her subagent geçici bir worktree alır; değişiklik yapmadan biterse worktree otomatik silinir, değişiklik varsa periyodik tarama iş kaybetmeden silebilene kadar kalır.

Özet

Git worktree, Claude Code'u paralel çalıştırmanın dosya çakışmasını ortadan kaldıran temel yapı taşı. claude -w <isim> her oturuma .claude/worktrees/ altında ayrı bir checkout ve dal verir; .worktreeinclude gizli dosyaları, worktree.symlinkDirectories büyük bağımlılık klasörlerini, worktree.sparsePaths monorepo'da yalnızca gereken klasörleri getirir. worktree.baseRef ile temiz origin/main ya da yerel HEAD arasında seçim yaparsınız, --worktree "#1234" ile bir PR'ı doğrudan izole ortamda açarsınız. Claude Code çıkışta işinizi korur, subagent ve arka plan worktree'lerini periyodik olarak temizler ve ana checkout'a yönelen düzenleme ile git komutlarını engeller. Kabuk yönlendirmeleri bu kontrollerin dışında kaldığı için izolasyonu izin kuralları ve sandbox ile tamamlamak gerekiyor.

Devam okumaları için: worktree'lerde çalışan yardımcıları kurmayı subagent rehberinde, arka planda çoklu oturum yönetimini Agent View rehberinde, worktree yolunu okuyan otomasyonları hooks rehberinde, Bash aracını izole etmeyi sandbox rehberinde bulabilirsiniz.