Skip to main content
git worktree adalah direktori kerja terpisah dengan file dan cabang sendiri, berbagi riwayat repositori dan remote yang sama dengan checkout utama Anda. Menjalankan setiap sesi Claude Code dalam worktree-nya sendiri berarti edit dalam satu sesi tidak akan pernah menyentuh file di sesi lain, sehingga Anda dapat memiliki Claude membangun fitur di satu terminal sambil memperbaiki bug di terminal kedua. Halaman ini mencakup isolasi worktree di CLI. Semuanya di bawah mengasumsikan repositori git. Untuk sistem kontrol versi lainnya, lihat Non-git version control. Aplikasi desktop membuat worktree untuk setiap sesi baru secara otomatis. Worktrees adalah salah satu dari beberapa cara untuk menjalankan Claude secara paralel. Mereka mengisolasi edit file, sementara subagents dan agent teams mengoordinasikan pekerjaan itu sendiri. Lihat Run agents in parallel untuk membandingkan pendekatan, atau lompat ke Isolate subagents with worktrees untuk menggunakan worktrees dan subagents bersama-sama.

​
Mulai Claude dalam worktree

Lewatkan --worktree atau -w untuk membuat worktree terisolasi dan memulai Claude di dalamnya. Secara default, worktree dibuat di bawah .claude/worktrees/<value>/ di root repositori Anda, pada cabang baru bernama worktree-<value>:
Untuk menempatkan worktrees di tempat lain, konfigurasikan hook WorktreeCreate. Jalankan perintah lagi dengan nama berbeda di terminal lain untuk memulai sesi terisolasi kedua:
Jika Anda menghilangkan nama, Claude menghasilkan satu seperti bright-running-fox:
Anda juga dapat meminta Claude untuk “bekerja dalam worktree” selama sesi, dan itu akan membuat satu dengan tool EnterWorktree. Setelah berada dalam worktree, Claude dapat beralih langsung ke worktree lain di bawah .claude/worktrees/ dengan memanggil EnterWorktree dengan jalur target. Worktree sebelumnya tetap berada di disk tanpa disentuh. Memasuki jalur di luar direktori .claude/worktrees/ repositori meminta persetujuan Anda terlebih dahulu, karena itu memindahkan direktori kerja sesi, akses tulis, dan konfigurasi proyek seperti CLAUDE.md dan settings ke lokasi tersebut. Aturan izin EnterWorktree atau memilih “jangan tanya lagi” tidak menekan prompt ini; hanya mode bypassPermissions yang melewatinya. Sebelum v2.1.206, Claude dapat memasuki jalur worktree yang ada tanpa bertanya. Mulai dari v2.1.198, memasuki atau keluar dari worktree juga memindahkan transkrip sesi ke penyimpanan proyek direktori tersebut, dengan cara yang sama seperti /cd melakukannya, sehingga /desktop dan --resume menemukan sesi di sana setelahnya. Worktrees yang dibuat oleh hook WorktreeCreate dikecualikan dan menyimpan transkrip di direktori peluncuran. Worktrees bekerja dengan sandboxing diaktifkan: sandbox memungkinkan penulisan ke direktori .git bersama repositori utama sehingga perintah seperti git commit dapat memperbarui refs dan indeks dari dalam linked worktree. Sebelum menggunakan --worktree secara interaktif di direktori untuk pertama kalinya, terima dialog kepercayaan workspace dengan menjalankan claude sekali di direktori tersebut. Jika kepercayaan belum diterima, --worktree keluar dengan kesalahan dan meminta Anda untuk menjalankan claude di direktori terlebih dahulu. Jalankan non-interaktif dengan -p melewati pemeriksaan kepercayaan, jadi claude -p --worktree melanjutkan tanpanya. Jika Claude Code tidak dapat memasuki direktori worktree saat startup, misalnya karena hook WorktreeCreate mencetak sesuatu selain direktori yang dibuat, atau karena direktori dihapus setelah diatur, Claude Code mencetak kesalahan yang menamai jalur dan keluar dengan kode 1. Sebelum v2.1.205, ini menghancurkan sesi, dan dengan -p itu terhenti selama sekitar 30 detik sebelum keluar dengan kode 0. Plugin yang diinstal pada cakupan proyek dari checkout utama juga dimuat dalam worktrees dari repositori yang sama, sehingga Anda tidak perlu menginstal ulang per worktree. Ini berlaku apakah Anda membuat worktree dengan --worktree atau dengan git worktree add. Memerlukan Claude Code v2.1.200 atau lebih baru.
Tambahkan .claude/worktrees/ ke .gitignore Anda sehingga konten worktree tidak muncul sebagai file yang tidak dilacak dalam checkout utama Anda.

​
Pilih cabang dasar

Worktrees bercabang dari cabang default repositori Anda, origin/HEAD, sehingga mereka dimulai dari pohon bersih yang cocok dengan remote. Ketika tidak ada yang mengambil repositori dalam 24 jam terakhir, Claude Code menyegarkan origin/HEAD dengan pengambilan cabang default, dibatasi pada lima detik, dan menggunakan ref yang disimpan secara lokal jika pengambilan gagal. Jika tidak ada remote yang dikonfigurasi, atau origin/HEAD tidak disimpan secara lokal dan tidak dapat diambil, worktree kembali ke HEAD lokal Anda saat ini. Penyegaran memerlukan Claude Code v2.1.208 atau lebih baru; sebelum itu, worktree baru menggunakan apa pun yang sudah disimpan secara lokal di origin/HEAD. Untuk selalu bercabang dari HEAD lokal, atur worktree.baseRef ke "head" dalam settings. Mengatur baseRef ke "head" membuat worktree baru membawa commit yang belum didorong dan status cabang fitur Anda, yang berguna saat mengisolasi subagent yang perlu beroperasi pada pekerjaan yang sedang berlangsung. Ketika sesi berjalan di dalam linked worktree, "head" diselesaikan ke HEAD worktree tersebut, bukan checkout utama. Pengaturan hanya menerima "fresh" atau "head", bukan git refs arbitrer:
Untuk bercabang dari pull request tertentu, lewatkan nomor PR dengan awalan #, atau URL pull request GitHub lengkap. Claude Code mengambil pull/<number>/head dari origin dan membuat worktree di .claude/worktrees/pr-<number>:
Untuk kontrol penuh atas cara pembuatan worktrees, konfigurasikan hook WorktreeCreate, yang menggantikan logika git worktree default sepenuhnya.

​
Gunakan kembali nama worktree

Menggunakan kembali nama worktree yang direktorinya sudah ada melanjutkan worktree tersebut. Worktree yang dilanjutkan disetel ulang ke base saat ini alih-alih melanjutkan di ujung lamanya ketika semua hal berikut berlaku:
  • Tidak memiliki perubahan yang belum dikomit atau file yang tidak dilacak.
  • Masih berada di cabang yang dibuat Claude Code untuk itu.
  • Tidak pernah berkomit, atau pull request-nya digabungkan dan cabang remote-nya dihapus.
Sebelum v2.1.208, nama yang digunakan kembali selalu melanjutkan worktree lama di ujung lamanya.

​
Salin file yang diabaikan git ke dalam worktrees

Worktree adalah checkout segar, jadi file yang tidak dilacak seperti .env atau .env.local dari repositori utama Anda tidak ada. Untuk menyalinnya secara otomatis saat Claude membuat worktree, tambahkan file .worktreeinclude ke root proyek Anda. File menggunakan sintaks .gitignore. Hanya file yang cocok dengan pola dan juga diabaikan git yang disalin, sehingga file yang dilacak tidak pernah diduplikasi. .worktreeinclude ini menyalin dua file env dan konfigurasi rahasia ke setiap worktree baru:
.worktreeinclude
Ini berlaku untuk worktrees yang dibuat dengan --worktree, subagent worktrees, dan sesi paralel dalam aplikasi desktop.

​
Isolasi subagents dengan worktrees

Subagents dapat berjalan dalam worktrees mereka sendiri sehingga edit paralel tidak bertabrakan. Minta Claude untuk “gunakan worktrees untuk agen Anda”, atau atur secara permanen pada subagent kustom dengan menambahkan isolation: worktree ke frontmatter. Setiap subagent mendapatkan worktree sementara yang dihapus secara otomatis saat subagent selesai tanpa perubahan. Worktrees subagent menggunakan base branch yang sama dengan --worktree, jadi mereka membuat cabang dari branch default repositori Anda kecuali worktree.baseRef diatur ke "head".

​
Bersihkan worktrees

Saat Anda keluar dari sesi worktree, pembersihan tergantung pada apakah Anda membuat perubahan:
  • Tidak ada perubahan yang belum dilakukan, tidak ada file yang tidak dilacak, dan tidak ada commit baru: worktree dan cabangnya dihapus secara otomatis. Jika sesi memiliki nama, Claude malah meminta sehingga Anda dapat menyimpan worktree untuk nanti
  • Perubahan yang belum dilakukan, file yang tidak dilacak, atau commit baru ada: Claude meminta Anda untuk menyimpan atau menghapus worktree. Menyimpan mempertahankan direktori dan cabang sehingga Anda dapat kembali nanti. Menghapus menghapus direktori worktree dan cabangnya, membuang semua perubahan yang belum dilakukan, file yang tidak dilacak, dan commit
  • Jalankan non-interaktif: worktrees yang dibuat dengan --worktree bersama dengan -p tidak dibersihkan secara otomatis karena tidak ada prompt keluar. Hapus dengan git worktree remove
Worktrees yang Claude buat untuk subagent dan sesi latar belakang dihapus secara otomatis setelah mereka lebih tua dari pengaturan cleanupPeriodDays Anda, asalkan mereka tidak memiliki perubahan yang belum dilakukan, tidak ada file yang tidak dilacak, dan tidak ada commit yang belum didorong. Worktrees yang Anda buat dengan --worktree tidak pernah dihapus oleh sapuan ini. Saat agen sedang berjalan, Claude menjalankan git worktree lock pada worktreenya sehingga pembersihan bersamaan tidak dapat menghapusnya. Kunci dilepaskan ketika agen selesai. Untuk membersihkan worktree yang disimpan oleh sapuan, jalankan git worktree remove, tambahkan --force jika worktree memiliki perubahan yang belum dilakukan atau file yang tidak dilacak. Di Windows, sebelum menghapus worktree, Claude Code menghapus sambungan NTFS atau symlink direktori apa pun pada kedalaman apa pun di dalamnya sebagai entri tautan, sehingga menghapus worktree tidak menghapus file yang ditunjuk tautan. Sebelum v2.1.205, Claude Code hanya menghapus tautan tingkat atas sebagai entri tautan, dan menghapus worktree dengan sambungan yang bersarang di subdirektori dapat menghapus isi direktori yang ditunjuk tautan di luar worktree.

​
Kelola worktrees secara manual

Untuk kontrol penuh atas lokasi worktree dan konfigurasi cabang, buat worktrees dengan Git secara langsung. Ini berguna saat Anda perlu checkout cabang yang ada tertentu atau menempatkan worktree di luar repositori. Buat worktree pada cabang baru:
Buat worktree dari cabang yang ada:
Mulai Claude dalam worktree:
Daftar worktrees Anda:
Hapus satu saat Anda selesai dengannya:
Lihat dokumentasi Git worktree untuk referensi perintah lengkap. Ingat untuk menginisialisasi lingkungan pengembangan Anda di setiap worktree baru: instal dependensi, atur lingkungan virtual, atau jalankan apa pun yang diperlukan setup proyek Anda.

​
Non-git version control

Isolasi worktree menggunakan git secara default. Untuk SVN, Perforce, Mercurial, atau sistem lainnya, konfigurasikan hook WorktreeCreate dan WorktreeRemove untuk menyediakan logika pembuatan dan pembersihan kustom. Karena hook menggantikan perilaku git default, .worktreeinclude tidak diproses saat Anda menggunakan --worktree. Salin file konfigurasi lokal apa pun di dalam skrip hook Anda. Hook WorktreeCreate ini membaca nama worktree dari stdin, checkout salinan kerja SVN segar, dan mencetak jalur direktori sehingga Claude Code dapat menggunakannya sebagai direktori kerja sesi:
Pasangkan dengan hook WorktreeRemove untuk membersihkan saat sesi berakhir. Lihat referensi hooks untuk skema input dan contoh penghapusan.

​
Lihat juga

Worktrees menangani isolasi file. Halaman terkait di bawah mencakup pendelegasian pekerjaan ke checkout terisolasi tersebut dan beralih antar sesi yang Anda buat: