Claude Code ve Codex için Git Worktree: Pratik Rehber

Bir repo üzerinde birden fazla kodlama ajanı çalıştırıyorsanız git worktree’ye ihtiyacınız var. Worktree’ler her ajanın kendi branch’inde, kendi klasöründe, aynı anda ve birbirinin ayağına basmadan çalışmasını sağlar.

Git worktree nedir?

Normal bir clone’da tek bir çalışma ağacı vardır: tek klasör, checkout edilmiş tek branch. Worktree ise aynı repoya bağlı, başka bir branch’in checkout edildiği ek bir çalışma klasörüdür. Tüm worktree’ler tek bir .git geçmişini paylaşır; herhangi birinde atılan commit diğerlerinde anında görünür, ama dosyaları ayrıdır.

Ajanlar açısından anlamı şu:

• Claude Code, feat/auth üzerinde ../atlas-auth içindeki dosyaları düzenleyebilir
• Codex, feat/search üzerinde ../atlas-search içindeki dosyaları düzenleyebilir
• Siz de ana klasörde, main üzerinde incelemeye ve uygulamayı çalıştırmaya devam edersiniz

Kimse kimsenin değişikliğini ezmez.

Her görev için bir worktree oluşturun

Ana repo klasörünüzden:

# new branch + new folder next to the repo
git worktree add ../atlas-auth -b feat/auth
 
# another one, starting from a specific branch
git worktree add ../atlas-search -b feat/search origin/main
 
# see them all
git worktree list

Sonra her klasörde bir ajan başlatın:

cd ../atlas-auth && claude
cd ../atlas-search && codex

Worktree klasörlerine görevlerinin adını verin. Bir ay sonra atlas-auth size bir şey ifade eder; wt2 etmez.

Ya da worktree’yi Claude Code oluştursun

Claude Code’un yeni sürümleri worktree’yi sizin yerinize oluşturabiliyor:

claude --worktree feature-auth   # or: claude -w feature-auth

Bu komut .claude/worktrees/feature-auth/ altında, worktree-feature-auth adlı yeni bir branch üzerinde bir worktree oluşturur ve Claude’u içinde başlatır. İkinci bir yalıtılmış oturum için ikinci bir terminalde başka bir adla tekrar çalıştırın. Oturumun ortasında Claude’dan “bir worktree’de çalışmasını” da isteyebilirsiniz.

Claude Code worktree belgelerinden birkaç ayrıntı:

• Worktree dosyaları ana checkout’unuzda untracked olarak görünmesin diye .claude/worktrees/ yolunu .gitignore dosyanıza ekleyin.
• Repoda en az bir commit olmalı.
• Çıkarken Claude temiz bir worktree’yi kaldırır (adlandırılmış olanlar için önce sorar), hâlâ değişiklik içeren bir worktree’yi tutup tutmayacağınızı da sorar.
• .worktreeinclude dosyası, her yeni worktree’ye kopyalanacak, git’in yok saydığı .env gibi dosyaları listeler.

Görevdeki tek ajan Claude Code ise claude --worktree kullanın. Klasör ve branch adını kendiniz seçmek ya da worktree’de Codex veya başka bir ajan çalıştırmak istiyorsanız düz git worktree add kullanın.

Ajan başlamadan önce her worktree’yi hazırlayın

Yeni bir worktree yalnızca git’in izlediği dosyaları içerir. Bir ajana teslim etmeden önce:

• Bağımlılıkları kurun. node_modules, virtualenv’ler ve build klasörleri paylaşılmaz. Her worktree’de npm install (ya da sizdeki karşılığını) çalıştırın. pnpm gibi ortak depo kullanan paket yöneticileri bunu hızlandırır.
• İzlenmeyen yapılandırmayı kopyalayın. .env dosyaları ve yerel ayarlar genelde git tarafından yok sayılır; uygulamanın çalışması için gerekenleri kopyalayın. claude --worktree kullanıyorsanız bunları .worktreeinclude dosyasına yazın.
• Farklı portlar kullanın. İki geliştirme sunucusu aynı anda 3000 portunu dinleyemez. İkincisini başka bir portta başlatın; örneğin PORT=3001 npm run dev.
• Talimatları izlenen dosyalarla paylaşın. CLAUDE.md ve AGENTS.md git’e commit’lenir, yani her worktree onları otomatik olarak alır.

İnceleme, merge ve temizlik

Bir ajan işini bitirdiğinde:

# in the worktree: check the work
git diff main...feat/auth
npm test
 
# in the main folder: merge
git merge feat/auth
 
# remove the worktree folder and its registration
git worktree remove ../atlas-auth
git branch -d feat/auth

Bir worktree klasörünü elle sildiyseniz, eskimiş kaydı temizlemek için git worktree prune çalıştırın.

Sık yapılan hatalar

• “Branch is already checked out.” Bir branch aynı anda yalnızca bir worktree’de checkout edilebilir. Bunun yerine her worktree için yeni bir branch oluşturun.
• Unutulan worktree’ler. Eski worktree’ler branch’leri hayatta tutar ve disk yer kaplar. Arada bir git worktree list çalıştırın.
• Kaldırırken commit’lenmemiş değişiklikler. Worktree’de değişiklik varsa git worktree remove reddeder. Önce commit’leyin ya da stash’leyin; gerçekten atmak istiyorsanız --force kullanın.
• Ana klasörü düzenleyen ajanlar. Her ajanı repo kökünden değil, kendi worktree klasörünün içinden başlatın.

Vibe Console’da worktree’ler

Vibe Console, ajanlar çalışırken worktree’leri gözünüzün önünde tutar:

• Kaynak Denetimi’ndeki (⌘⇧G) Worktree'ler sekmesi her worktree’yi branch’iyle listeler; ana worktree’yi ve detached checkout’ları işaretler.
• Yolunu yapıştırmak için bir worktree’yi terminale sürükleyin, ardından orada ⌘K ile bir ajan başlatın.
• İşiniz bittiğinde Worktree'yi kaldır onu temizler; hâlâ yerel değişiklikler varsa Zorla Kaldır onayı ister. Ana worktree korunur.
• Izgara dokuz terminale kadar gösterir; her worktree’nin ajanı kendi paneline sahip olabilir. Bkz. ajanları paralel çalıştırma.

Worktree’leri yukarıdaki gibi git worktree add ya da claude --worktree ile oluşturun; ikisi de listede hemen görünür.

Sık sorulan sorular

Worktree’ler çok disk alanı kaplar mı?

Yalnızca checkout edilen dosyalar ve içlerine kurduklarınız kadar. Git geçmişi paylaşılır.

Worktree mi, ayrı clone’lar mı?

Worktree. Tek bir geçmişi paylaşırlar; branch’ler ve commit’ler her yerde anında erişilebilir olur, temizlik de tek komuttur.

İki ajan aynı worktree’yi paylaşabilir mi?

Yalnızca en fazla biri dosya düzenliyorsa. Sadece okuyan bir inceleyici ajan, kodu yazan ajanla aynı worktree’yi paylaşabilir.

14 gün ücretsiz deneyin: Vibe Console’u indirin.