Git Worktrees

Git Worktrees ile Paralel Oturumlar Çalıştırma

Claude Code, aynı depoda birden fazla oturumu çakışmadan çalıştırabilmeniz için git worktree izolasyonu sunar. Her Claude Code oturumu kendi worktree'sinde çalıştığında, bir oturumdaki düzenlemeler diğer oturumdaki dosyalara asla dokunmaz. Böylece bir terminalde Claude'a yeni bir özellik geliştirirken, diğer terminalde bir hatayı düzeltmesini söyleyebilirsiniz.

Bu sayfa CLI'da worktree izolasyonunu kapsar. Aşağıdaki her şey bir git deposu olduğunu varsayar. Diğer sürüm kontrol sistemleri için Git dışı sürüm kontrolü bölümüne bakın.

Masaüstü uygulaması, her yeni oturum için otomatik olarak bir worktree oluşturur.

Worktreeler, Claude'u paralel çalıştırmanın birkaç yolundan biridir. Dosya düzenlemelerini izole ederken, subagent'lar ve agent ekipleri işin kendisini koordine eder. Yaklaşımları karşılaştırmak için Agent'ları paralel çalıştırma sayfasına bakın veya worktreeleri subagent'larla birlikte kullanmak için Subagent'ları worktreelerle izole etme bölümüne geçin.

Worktree'de Claude'u Başlatma (Start Claude in a worktree)

--worktree veya -w bayrağını kullanarak izole bir worktree oluşturun ve Claude'u burada başlatın. Varsayılan olarak worktree, depo kökündeki .claude/worktrees/<değer>/ altında, worktree-<değer> adında yeni bir dalda oluşturulur:

claude --worktree feature-auth

Komutu başka bir terminalde farklı bir adla tekrar çalıştırarak ikinci bir izole oturum başlatabilirsiniz:

claude --worktree bugfix-123

Eğer isim vermezseniz, Claude bright-running-fox gibi bir isim üretir:

claude --worktree

Ayrıca bir oturum sırasında Claude'a "worktree'de çalış" diyebilirsiniz; Claude EnterWorktool aracını kullanarak bir worktree oluşturur.

--worktree kullanmadan önce, dizinde çalışma alanı güvenini kabul etmek için o dizinde bir kez claude çalıştırın. Güven henüz kabul edilmemişse, --worktree bir hata ile çıkar ve önce dizinde claude çalıştırmanızı ister; bu -p ile birlikte kullanıldığında da geçerlidir.

Ana kontrolünüzde .claude/worktrees/ dizinini izlenmeyen dosyalar olarak görünmemesi için .gitignore dosyanıza ekleyin.

Temel Dalı Seçme (Choose the base branch)

Worktreeler, deponuzun varsayılan dalı olan origin/HEAD'den dallanır, böylece uzak sunucuyla eşleşen temiz bir ağaçtan başlarlar. Eğer uzak sunucu yapılandırılmamışsa veya getirme işlemi başarısız olursa, worktree mevcut yerel HEAD'inize döner.

Her zaman yerel HEAD'den dallanmak için ayarlarda worktree.baseRef değerini "head" olarak ayarlayın:

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

baseRef değerini "head" yapmak, yeni worktreelerin itilmemiş commit'lerinizi ve özellik dalı durumunuzu taşımasını sağlar; bu, devam eden işler üzerinde çalışması gereken subagent'ları izole ederken kullanışlıdır.

Ayarlar yalnızca "fresh" veya "head" değerlerini kabul eder, rastgele git referanslarını değil.

Belirli bir pull request'ten dallanmak için, PR numarasını # ile önekleyerek veya tam bir GitHub pull request URL'si geçin. Claude Code, origin'den pull/<sayı>/head'i getirir ve worktree'yi .claude/worktrees/pr-<sayı> konumunda oluşturur:

claude --worktree "#1234"

Worktreelerin nasıl oluşturulacağı üzerinde tam kontrol için, varsayılan git worktree mantığını tamamen değiştiren bir WorktreeCreate hook'u yapılandırın.

Gitignore Edilmiş Dosyaları Worktreelere Kopyalama (Copy gitignored files into worktrees)

Bir worktree, temiz bir kontrol olduğu için ana deponuzdaki .env veya .env.local gibi izlenmeyen dosyalar mevcut değildir. Claude bir worktree oluşturduğunda bunları otomatik olarak kopyalamak için proje köküne bir .worktreeinclude dosyası ekleyin. Dosya .gitignore sözdizimini kullanır. Yalnızca bir kalıpla eşleşen ve aynı zamanda gitignore edilmiş dosyalar kopyalanır; böylece izlenen dosyalar asla çoğaltılmaz.

Bu .worktreeinclude dosyası, her yeni worktree'ye iki env dosyası ve bir secrets yapılandırması kopyalar:

.env
.env.local
config/secrets.json

Bu, --worktree ile oluşturulan worktreeler, subagent worktreeleri ve masaüstü uygulamasındaki paralel oturumlar için geçerlidir.

Subagent'ları Worktreelerle İzole Etme (Isolate subagents with worktrees)

Subagent'lar, paralel düzenlemelerin çakışmaması için kendi worktreelerinde çalışabilir. Claude'a "agent'ların için worktreeler kullan" deyin veya özel bir subagent'ın frontmatter'ına isolation: worktree ekleyerek kalıcı olarak ayarlayın.

Her subagent, geçici bir worktree alır. Subagent değişiklik yapmadan işini bitirdiğinde bu worktree otomatik olarak kaldırılır.

Worktreeleri Temizleme (Clean up worktrees)

Bir worktree oturumundan çıktığınızda temizlik, değişiklik yapıp yapmadığınıza bağlıdır:

Worktreeleri Manuel Yönetme (Manage worktrees manually)

Worktree konumu ve dal yapılandırması üzerinde tam kontrol için worktreeleri doğrudan Git ile oluşturun. Bu, belirli bir mevcut dalı kontrol etmeniz veya worktree'yi depo dışına yerleştirmeniz gerektiğinde kullanışlıdır.

Yeni bir dalda worktree oluşturma:

git worktree add ../project-feature-a -b feature-a

Mevcut bir daldan worktree oluşturma:

git worktree add ../project-bugfix bugfix-123

Worktree'de Claude'u başlatma:

cd ../project-feature-a && claude

Worktreelerinizi listeleme:

git worktree list

İşiniz bittiğinde kaldırma:

git worktree remove ../project-feature-a

Tam komut referansı için Git worktree dokümantasyonuna bakın.

Her yeni worktree'de geliştirme ortamınızı başlatmayı unutmayın: bağımlılıkları yükleyin, sanal ortamları kurun veya projenizin gerektirdiği diğer kurulumları yapın.

Git Dışı Sürüm Kontrolü (Non-git version control)

Worktree izolasyonu varsayılan olarak git kullanır. SVN, Perforce, Mercurial veya diğer sistemler için, özel oluşturma ve temizleme mantığı sağlamak üzere WorktreeCreate ve WorktreeRemove hook'larını yapılandırın.

Hook, varsayılan git davranışını değiştirdiği için --worktree kullanıldığında .worktreeinclude işlenmez. Bunun yerine, yerel yapılandırma dosyalarını hook betiğinizin içinde kopyalayın.

Bu WorktreeCreate hook'u, worktree adını stdin'den okur, yeni bir SVN çalışma kopyasını kontrol eder ve Claude Code'un oturumun çalışma dizini olarak kullanması için dizin yolunu yazdırır:

{
  "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\"'"
          }
        ]
      }
    ]
  }
}

Bunu, oturum sona erdiğinde temizlik yapacak bir WorktreeRemove hook'u ile eşleştirin. Giriş şeması ve bir kaldırma örneği için hook referansına bakın.

Ayrıca Bakınız (See also)

Worktreeler dosya izolasyonunu yönetir. Aşağıdaki ilgili sayfalar, işi bu izole kontrollere devretmeyi ve oluşturduğunuz oturumlar arasında geçiş yapmayı kapsar:

• Subagent'lar: Bir oturum içinde izole agent'lara iş devretme
• Agent ekipleri: Birden fazla Claude oturumunu otomatik olarak koordine etme
• Oturumları yönetme: Konuşmaları adlandırma, devam ettirme ve aralarında geçiş yapma
• Masaüstü paralel oturumları: Masaüstü uygulamasında worktree destekli oturumlar

Örnek kullanım senaryosu

Bir e-ticaret projesinde çalıştığınızı düşünün. Aynı anda iki farklı görevi halletmeniz gerekiyor: kullanıcı kimlik doğrulama modülüne yeni bir özellik eklemek ve ödeme sayfasındaki bir hatayı düzeltmek.

1. İlk terminalde, kimlik doğrulama özelliği için izole bir worktree oturumu başlatın:

   claude --worktree feature-auth
   

   Bu komut, .claude/worktrees/feature-auth/ altında worktree-feature-auth dalında yeni bir worktree oluşturur ve Claude'u burada başlatır.

2. Claude'a şu komutu verin: "Kullanıcı kayıt formuna e-posta doğrulama adımı ekle. Gerekli dosyaları düzenle ve testleri çalıştır."

3. İkinci terminalde, hata düzeltmesi için başka bir worktree oturumu başlatın:

   claude --worktree bugfix-123
   

4. Bu oturumda Claude'a şunu söyleyin: "Ödeme sayfasında sepet boşken 'Siparişi Tamamla' butonu görünüyor. Bunu gizle ve birim testini güncelle."

5. İki oturum tamamen izole çalışır. Birindeki dosya değişiklikleri diğerini etkilemez.

6. Kimlik doğrulama özelliği tamamlandığında, oturumdan çıkın. Değişiklikler kaydedilmişse Claude size worktree'yi koruyup korumayacağınızı sorar. "Koru" derseniz, daha sonra cd .claude/worktrees/feature-auth && claude ile geri dönebilirsiniz.

7. Hata düzeltmesi bittiğinde, değişiklikleri commit edin ve oturumdan çıkın. Worktree otomatik olarak temizlenir.

8. Her iki özellik de test edildikten sonra, worktreelerdeki commit'leri ana deponuza birleştirin veya pull request olarak gönderin.

Bu yaklaşım, özellikle büyük ekiplerde veya karmaşık projelerde, bir geliştiricinin aynı anda birden fazla görevi çakışma riski olmadan yürütmesine olanak tanır.