Jalankan sesi paralel dengan worktrees

​

Mulai Claude dalam worktree

claude --worktree feature-auth

​

Atur lingkungan worktree

​

Minta Claude untuk membuat worktree

​

Bersihkan worktrees

• Worktree bersih: untuk sesi tanpa nama, Claude menghapus worktree dan cabangnya secara otomatis. Sesi bernama meminta Anda terlebih dahulu sehingga Anda dapat menyimpan worktree untuk nanti
• Worktree memiliki pekerjaan di dalamnya: Claude meminta Anda untuk menyimpan atau menghapus worktree. Menyimpan mempertahankan direktori dan cabang sehingga Anda dapat kembali nanti. Menghapus menghapus direktori worktree dan cabangnya, bersama dengan semua pekerjaan di dalamnya
• Status worktree tidak dapat diverifikasi: ketika Claude Code tidak dapat menghitung perubahan worktree atau tidak dapat memeriksa checkout submodulnya, Claude meminta Anda daripada menghapus worktree secara otomatis. Prompt tersebut menyebutkan apa yang tidak dapat diperiksa

​

Lanjutkan sesi worktree

• Direktori peluncuran: lanjutkan dari checkout utama atau direktori lain dari repositori. Claude Code memasuki kembali worktree yang dibuat dengan git di bawah .claude/worktrees/ bahkan saat Anda meluncurkan dari dalamnya. Saat Anda meluncurkan dari dalam worktree lain, Claude Code memasuki kembali hanya jika dapat menjaminnya dari sana: worktree yang merupakan repositorinya sendiri, satu tanpa metadata git, atau peluncuran dari subdirektori worktree yang Anda buat dengan git worktree add menolak, jadi luncurkan dari checkout utama.
• --fork-session: sesi yang di-fork dimulai di direktori tempat Anda meluncurkan Claude, dan Claude Code meninggalkan worktree sesi asli tanpa disentuh.
• Worktree yang dihapus: jika direktori worktree tidak lagi ada, Claude Code melanjutkan sesi di direktori tempat Anda meluncurkan Claude. Itu memberi tahu Anda worktree hilang dan menghapus pengikatan worktree sesi.

​

Bagaimana Claude Code memberlakukan isolasi

• Edit file: Claude Code memblokir Edit, Write, atau NotebookEdit yang menargetkan jalur dalam checkout utama.
• Direktori kerja perintah: Claude Code memblokir perintah Bash, PowerShell, atau Monitor yang direktori kerjanya diselesaikan ke checkout utama, atau yang direktori kerjanya tidak dapat diverifikasi tetap di luar itu.
• Pengalihan git: Claude Code memblokir perintah Bash atau Monitor yang mengalihkan git ke checkout utama. Pengalihan dapat datang melalui git -C, --git-dir, variabel GIT_DIR atau GIT_WORK_TREE, atau cd ke checkout utama sebelum menjalankan git.
• Bentuk perintah: Claude Code memblokir perintah Bash atau Monitor saat tidak dapat memverifikasi dari teks perintah bahwa git apa pun yang dijalankan perintah tetap berada di dalam worktree. Itu terjadi, misalnya, saat nama perintah dihitung saat runtime, saat sintaks tidak dapat diuraikan, atau saat ekspansi seperti ${!name} atau ${ command; } dapat menjalankan perintah yang teks tidak jelaskan. Claude Code memberi tahu Claude cara menulis ulang perintah yang ditolak, seperti membaginya menjadi perintah biasa yang terpisah. Anda tidak dapat mematikan pemeriksaan ini.

​

Isolasi subagents dengan worktrees

---
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.

​

Bersihkan subagent dan worktrees sesi latar belakang

• Worktree masih menyimpan pekerjaan: file yang diubah atau tidak dilacak, atau commit yang belum didorong.
• Submodul yang diperiksa dalam worktree menyimpan file yang diubah atau tidak dilacak, atau Claude Code tidak dapat memeriksa submodul worktree. Pemeriksaan ini memerlukan Claude Code v2.1.274 atau lebih baru.
• Salah satu dari empat kasus yang juga memblokir pembuatan worktree berlaku: Claude Code tidak dapat menentukan driver filter mana yang didefinisikan konfigurasi repositori, atau menemukan pengaturan di sana yang tidak dapat dimatikan.
• Worktree milik sesi --worktree yang belum Anda kirim ke latar belakang, apa pun usianya.
• Anda membuat worktree sendiri dengan git worktree add, bahkan jika Anda kemudian menjalankan sesi --worktree <name> di dalamnya dan mengirimnya ke latar belakang.

​

Sesuaikan pembuatan worktree

​

Pilih cabang dasar

• "fresh" (default): membuat cabang dari cabang default repositori di remote, biasanya main, jadi worktree dimulai dari pohon bersih yang cocok dengan remote.
• "head": membuat cabang dari HEAD lokal saat ini Anda, jadi worktree membawa commit yang belum didorong dan status cabang fitur Anda. Gunakan ini saat mengisolasi subagents yang perlu beroperasi pada pekerjaan yang sedang berlangsung. Di dalam worktree, "head" diselesaikan ke HEAD worktree itu, bukan checkout utama.

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

​

Buat cabang dari pull request

claude --worktree "#1234"

• github.com: mengambil pull/<number>/head
• gitlab.com: mengambil merge-requests/<number>/head
• GitHub Enterprise, GitLab yang dikelola sendiri, atau host lainnya: mencoba pull/<number>/head terlebih dahulu, kemudian merge-requests/<number>/head

​

Salin file yang diabaikan git ke dalam worktrees

.env
.env.local
config/secrets.json

​

Gunakan kembali nama worktree

• Tidak memiliki perubahan yang belum dikomit atau file yang tidak dilacak.
• Masih berada di cabang yang dibuat Claude Code untuk itu.
• Tidak memiliki commit sendiri, atau pull request atau merge request-nya digabungkan dan cabang remote-nya dihapus.

• Worktree gagal salah satu kondisi.
• Claude Code tidak dapat memverifikasi keadaan worktree.
• worktree.baseRef adalah "head".
• Nama adalah referensi pull request atau merge request.

​

Ganti pembuatan worktree dengan hook

​

Apa yang dibagikan worktrees dengan checkout utama

• Direktori .git repositori: perintah git dalam worktree menulis ke direktori .git bersama repositori utama, dan sandboxing memungkinkan penulisan tersebut, jadi perintah seperti git commit bekerja dari dalam worktree dengan sandbox diaktifkan.
• Plugins: plugin yang diinstal pada cakupan proyek dari checkout utama juga dimuat dalam worktrees dari repositori yang sama, jadi Anda tidak perlu menginstal ulang per worktree. Memerlukan Claude Code v2.1.200 atau lebih baru.
• Persetujuan izin: memilih “Ya, dan jangan tanya lagi” untuk perintah Bash dalam sesi worktree menyimpan aturan ke .claude/settings.local.json checkout utama, jadi itu berlaku dalam checkout utama dan di setiap worktree lain dari repositori, dan itu bertahan penghapusan worktree. Di Windows dan dalam kasus lain di mana Claude Code tidak menggunakan root repositori, aturan tetap dengan worktree itu. Sebelum v2.1.211, persetujuan yang diberikan dalam worktree disimpan di dalam worktree itu, tidak berlaku di tempat lain, dan hilang saat worktree dihapus. Lihat di mana persetujuan disimpan.
• Skills, agents, dan commands yang tidak dilacak: ketika checkout worktree tidak memiliki direktori .claude/skills di akarnya, misalnya karena .claude/skills Anda diabaikan oleh git, Claude Code memuat project skills checkout utama dalam sesi worktree. Dalam worktree dengan direktori .claude/skills sendiri, hanya salinan itu yang dimuat. Pembacaan yang sama mencakup .claude/agents dan .claude/commands. Untuk skills, pembacaan memerlukan Claude Code v2.1.277 atau lebih baru.

​

Kelola worktrees secara manual

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

git worktree add ../project-bugfix fix-issue-456

cd ../project-feature-a
claude

git worktree list

git worktree remove ../project-feature-a

​

Non-git version control

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

​

Troubleshooting

​

Claude Code tidak dapat memasuki worktree saat startup

​

Pembuatan worktree gagal pada jalur symlinked

​

File Git LFS adalah file pointer dalam worktree yang dibuat Claude Code

• Could not read the repository git config to neutralize filter drivers: Claude Code tidak dapat membaca .git/config repositori, misalnya karena izinnya. Perbaiki itu dan coba lagi.
• The repository git config defines a filter driver whose name cannot be neutralized (contains "=" or a newline): ganti nama atau hapus driver filter itu dalam .git/config dan coba lagi.
• The repository git config has a conditional include (includeIf): pindahkan pengaturan yang includeIf dalam .git/config tarik langsung ke dalam file itu, hapus includeIf, dan coba lagi. includeIf dalam konfigurasi git global Anda tidak memicu ini.
• Git was not run: the repository's own git config sets <key>: pesan menamai kunci yang menunjuk Git LFS ke program untuk dijalankan, seperti lfs.customtransfer.<name>.path atau lfs.standalonetransferagent. Jika pengaturan itu milik Anda, pindahkan ke konfigurasi git global Anda. Jika Anda tidak mengenalinya, hapus dari konfigurasi git repositori, karena alat atau checkout yang Anda tidak percayai mungkin telah menulisnya. Coba lagi setelah kunci hilang dari konfigurasi repositori.

​

Claude Code menolak untuk menggunakan worktree

• Mengatakan launch from the parent checkout atau Run the resume from the project checkout: Anda meluncurkan Claude Code dari dalam worktree. Luncurkan dari checkout utama; worktree tidak memerlukan rekreasi.
• Mengatakan it cannot be resumed or re-entered: tidak ada dalam sesi ini yang menjamin worktree dari tempat Anda meluncurkan. Buat ulang; direktori dan pekerjaan-nya tetap berada di disk untuk pemulihan manual, dan saat worktree memiliki checkout induk, melanjutkan dari sana juga berfungsi.
• Mengatakan it contains the protected checkout: direktori yang ditolak adalah induk checkout utama Anda, seperti direktori home Anda. Jangan hapus. Ubah jalur worktree, seperti jalur yang dikembalikan hook WorktreeCreate Anda atau target EnterWorktree, sehingga worktree tidak berisi checkout.
• Mengatakan the protected checkout <path> has a .git entry that could not be examined atau has git metadata that could not be resolved: masalahnya adalah metadata git checkout utama, bukan worktree. Jangan hapus worktree, dan abaikan saran pesan untuk membuat ulangnya, yang tidak berlaku untuk dua akhiran ini. Perbaiki checkout utama, misalnya masalah izin atau penolakan git dubious ownership pada .git-nya, dan coba lagi.
• Mengatakan its recorded path has a network spelling: Claude Code tidak pernah melanjutkan ke worktree di jalur jaringan. Buat ulang worktree di jalur lokal.
• Akhiran lainnya: pesan menamai masalah dan perbaikannya, seperti menghapus pengalihan core.worktree atau membuat ulang worktree; ikuti. Sebelum menghapus direktori yang pesannya mengatakan identitas git tidak dapat diverifikasi, tangani penyebab yang dinamai terlebih dahulu, misalnya symlink dalam jalur worktree atau git itu sendiri gagal berjalan, karena direktori mungkin sehat. Saat Anda membuat ulang, selamatkan perubahan apa pun yang Anda butuhkan dari direktori lama terlebih dahulu; itu tetap berada di disk.

​

Sesi melanjutkan di luar worktree-nya

• Error: cannot resume into worktree <path>: ...This session was not started. untuk penolakan yang ditunjukkan tabel sebagai Did not re-enter. Claude Code menghapus pengikatan worktree sebelum keluar, dan kesalahan mengatakan demikian; saat berikutnya Anda melanjutkan percakapan, sesi berlanjut di direktori saat ini tanpa isolasi worktree. Sebelum v2.1.260, Claude Code tidak menulis pengikatan yang dihapus, jadi setiap percobaan ulang resume yang sama gagal dengan kesalahan yang sama. Jika Anda menekan penulisan transkrip, penghapusan tidak dapat disimpan. Kesalahan kemudian mengatakan perintah yang sama akan ditolak lagi, dan menamai --fork-session dan memulai percakapan baru sebagai cara untuk melanjutkan tanpa worktree.
• Error: could not verify worktree <path> for this resume, so the resume was aborted... untuk Could not verify
• Error: ...The worktree binding is kept. untuk Could not re-enter
• Notice: the worktree <path> for this session no longer exists... untuk worktree yang hilang; Claude Code mencetaknya dan melanjutkan sesi, seperti resume interaktif

​

Lihat juga

• Subagents: delegasikan pekerjaan ke agen terisolasi dalam sesi
• Cross-session messaging: biarkan sesi dalam worktrees Anda melewatkan temuan satu sama lain
• Agent teams: koordinasikan beberapa sesi Claude secara otomatis
• Manage sessions: beri nama, lanjutkan, dan beralih antar percakapan
• Desktop parallel sessions: sesi yang didukung worktree dalam aplikasi desktop