Langsung ke konten utama
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>: 
claude --worktree feature-auth
Untuk menempatkan worktrees di tempat lain, konfigurasikan hook WorktreeCreate. Jalankan perintah lagi dengan nama berbeda di terminal lain untuk memulai sesi terisolasi kedua: 
claude --worktree bugfix-123
Jika Anda menghilangkan nama, Claude menghasilkan satu seperti bright-running-fox: 
claude --worktree
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. 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.
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. Jika tidak ada remote yang dikonfigurasi atau pengambilan gagal, worktree kembali ke HEAD lokal Anda saat ini. 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. Pengaturan hanya menerima "fresh" atau "head", bukan git refs arbitrer: 
{
  "worktree": {
    "baseRef": "head"
  }
}
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>: 
claude --worktree "#1234"
Untuk kontrol penuh atas cara pembuatan worktrees, konfigurasikan hook WorktreeCreate, yang menggantikan logika git worktree default sepenuhnya.

​
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
.env
.env.local
config/secrets.json
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.

​
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: 
git worktree add ../project-feature-a -b feature-a
Buat worktree dari cabang yang ada: 
git worktree add ../project-bugfix bugfix-123
Mulai Claude dalam worktree: 
cd ../project-feature-a && claude
Daftar worktrees Anda: 
git worktree list
Hapus satu saat Anda selesai dengannya: 
git worktree remove ../project-feature-a
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: 
{
  "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\"'"
          }
        ]
      }
    ]
  }
}
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: