Git worktree dalam Claude Code: sesi selari

Maklumat praktikal tentang penggunaan Ailoot tersedia dalam dokumentasi.

Apakah git worktree dalam Claude Code#

Melancarkan beberapa ejen secara serentak dalam folder yang sama ialah masalah asas vibe-coding pada kelajuan tahun 2026. Agen AI menulis kod lebih pantas daripada kemampuan seseorang untuk menjejaki siapa sedang mengusahakan apa. Tanpa pengasingan fail, melancarkan dua sesi Claude Code secara serentak dalam satu direktori akan menyebabkan satu sesi menindih kerja sesi yang lain.

Git worktree menyelesaikan masalah ini pada peringkat sistem fail. Anda mempunyai satu direktori utama untuk bekerja. Arahan claude --worktree feature-auth mencipta folder .claude/worktrees/feature-auth/ pada branch berasingan dan memulakan Claude Code di situ. Fail-failnya diasingkan. Perubahan dalam satu sesi tidak kelihatan kepada sesi yang lain sehingga anda menggabungkannya secara jelas.

Dokumentasi rasmi Anthropic menerangkannya begini:

Petunjuk untuk semakan kendiri: jika anda pernah menerima commit yang separuh daripada failnya hasil kerja orang lain, anda perlukan worktree.

Perbezaan git worktree dengan branch biasa#

Aliran kerja Git standard: anda berada pada branch main lalu menjalankan git checkout feature-x—Git menulis ganti fail salinan kerja. npm run dev yang sedang berjalan rosak kerana package.json berubah di bawahnya. Anda menyimpan perubahan yang belum di-commit dengan git stash dan menunggu IDE mengindeks semula. Anda beralih kembali dan semuanya ditulis ganti sekali lagi, jadi anda perlu membuat stash dan pop sekali lagi.

Git worktree memberikan pilihan lain: daripada menukar satu folder antara branch, anda mencipta folder kedua untuk branch lain. Arahan git worktree add ../project-feature-x feature-x mencipta direktori ../project-feature-x/ dengan fail daripada branch feature-x. main kekal dalam folder asal, dan pelayan pembangunan terus berjalan.

Sebelum ini, mod worktree dalam Claude Code perlu disediakan secara manual: git worktree add, kemudian cd, kemudian claude—dan ulang dalam setiap terminal. Bendera --worktree (juga -w) melakukan ketiga-tiganya dengan satu arahan.

Melancarkan sesi selari pertama: bendera --worktree#

Contoh minimum. Buka terminal pertama di akar projek:

claude --worktree feature-auth

Claude Code melakukan tiga perkara:

1. Mencipta .claude/worktrees/feature-auth/ dengan salinan origin/HEAD (biasanya branch lalai anda).
2. Mencipta branch worktree-feature-auth yang baharu.
3. Memulakan sesi dalam folder ini.

Buka terminal kedua di folder akar repositori yang sama:

claude --worktree bugfix-123

Selesai. Dua sesi Claude Code, fail berbeza pada cakera, branch Git yang berbeza. Jika anda menulis kod pengesahan dalam sesi pertama dan membaiki ujian yang gagal dalam sesi kedua, kedua-duanya tidak mungkin mengganggu satu sama lain secara fizikal.

Jika anda tidak mahu menaip nama, Claude akan menciptanya:

claude --worktree
# → mencipta sesuatu seperti .claude/worktrees/bright-running-fox/

Petua untuk pemula Git: tambahkan .claude/worktrees/ pada .gitignore. Jika tidak, apabila anda menjalankan git status dalam folder utama, kandungan semua worktree akan kelihatan sebagai fail yang tidak dijejak:

# .gitignore
.claude/worktrees/

Perkara yang perlu dielakkan: sebelum pelancaran --worktree pertama dalam direktori baharu, masuk ke dalamnya dengan claude biasa (tanpa bendera) dan terima dialog kepercayaan ruang kerja. Jika tidak, bendera itu gagal dengan ralat “trust not accepted”—termasuk jika digabungkan dengan -p untuk mod tanpa kepala.

Lokasi worktree dan cara mencarinya#

Lokasi lalai ditetapkan: .claude/worktrees/<value>/ di akar repositori. Jika projek anda berada di ~/dev/my-app/, worktree feature-auth akan berada di ~/dev/my-app/.claude/worktrees/feature-auth/.

Untuk susun atur bukan standard (contohnya, jika anda mahu worktree berada di luar repositori), terdapat hook WorktreeCreate—huraian lanjut di bawah dalam bahagian tentang SVN dan Mercurial.

Dalam satu sesi Claude, anda boleh bertukar ke worktree sedia ada yang lain. Cakap sahaja dalam sembang: “beralih ke .claude/worktrees/bugfix-123,” lalu Claude akan memanggil alat EnterWorktree. Folder semasa kekal tanpa disentuh—anda boleh kembali dengan cara yang sama.

Arahan Git standard memaparkan senarai semua worktree, termasuk worktree utama dan yang dicipta secara manual:

git worktree list

Outputnya akan kelihatan seperti ini:

/home/user/dev/my-app                  abc1234 [main]
/home/user/dev/my-app/.claude/worktrees/feature-auth  def5678 [worktree-feature-auth]
/home/user/dev/my-app/.claude/worktrees/bugfix-123    9876fed [worktree-bugfix-123]

Menyalin .env dan rahsia: fail .worktreeinclude#

Apabila --worktree mencipta folder baharu, folder itu hanya menerima perkara yang telah di-commit ke Git. .env yang mengandungi kunci API dan .env.local yang mengandungi konfigurasi setempat berada dalam .gitignore, maka kedua-duanya tiada dalam worktree. Akibatnya, npm run dev yang pertama gagal dengan “MISSING DATABASE_URL”.

Penyelesaian buatan sendiri ialah menyalin .env secara manual selepas setiap --worktree. Ia berfungsi sekali, kemudian terlupa. Penyelesaian Anthropic ialah fail .worktreeinclude di akar projek yang menyenaraikan fail diabaikan Git untuk disalin secara automatik ke setiap worktree baharu.

Cipta fail .worktreeinclude di akar repositori:

.env
.env.local
config/secrets.json

Sintaksnya sama seperti .gitignore. Anda boleh menggunakan corak glob:

.env*
*.local
config/*.json
.vscode/settings.json

Anthropic memberikan peraturan yang jelas untuk mengelakkan kesilapan:

Dengan kata lain, anda tidak boleh tersalin package.json secara tidak sengaja melalui .worktreeinclude—fail itu tidak berada dalam .gitignore. Selamat untuk meletakkan sebarang corak di situ.

.worktreeinclude yang sama berfungsi dalam tiga mod: --worktree manual, worktree automatik untuk subagen (lihat di bawah) dan sesi daripada aplikasi desktop Claude.

Worktree daripada pull request untuk semakan kod#

Senario semakan kod biasa: rakan sekerja menghantar PR; anda perlu memeriksa kod, menjalankan ujian dan meninggalkan komen. Dengan git checkout pull/1234/head biasa, anda menukar salinan kerja sekali lagi dan mengganggu sesi aktif.

Dengan bendera --worktree, hanya satu arahan diperlukan:

claude --worktree "#1234"

Perkara yang berlaku: Claude Code menjalankan git fetch origin pull/1234/head, mencipta worktree di .claude/worktrees/pr-1234/ dan checkout branch PR. Sesi pun bermula. Anda boleh terus memintanya “baca diff, jalankan ujian dan cari ralat logik”—sementara Claude bekerja, sesi utama anda pada main terus berjalan.

Sintaks alternatif ialah URL penuh pull request:

claude --worktree https://github.com/OWNER/REPO/pull/1234

Penggunaan dalam projek sebenar: memadankan claude --worktree "#N" dengan subagen penyemak kod anda sendiri memberikan semakan automatik dalam masa satu atau dua minit. Lancarkannya di latar belakang, teruskan kerja dalam tetingkap utama dan kembali kepada hasil melalui claude agents.

Branch asas: worktree.baseRef untuk fresh atau head#

Tetapan lalainya begini: setiap worktree baharu bermula daripada origin/HEAD. Kelebihannya ialah permulaan bersih yang pasti sepadan dengan perkara yang akan dilihat oleh CI. Kekurangannya ialah perubahan belum di-commit atau beberapa commit setempat yang mendahului remote pada branch semasa anda tidak akan disertakan dalam worktree baharu.

Untuk memulakan worktree daripada commit HEAD setempat semasa, tambah ini ke .claude/settings.json (atau tetapan global):

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

Kini claude --worktree experimental-feature bermula daripada HEAD setempat semasa. Ini berguna apabila ciri sudah mempunyai commit setempat belum dipush. Ia tidak merangkumi suntingan dijejaki yang masih belum dikomit. Jika subagen memerlukan suntingan itu, simpan dan pindahkan perubahan diperlukan secara jelas, kemudian periksa diff destinasi; jangan kelirukan pemindahan itu dengan .worktreeinclude, yang mengendalikan fail setempat diabaikan.

Tetapan ini menerima tepat dua nilai: "fresh" (= origin/HEAD) dan "head" (= HEAD setempat). Ref sewenang-wenangnya seperti "feature-branch" atau hash commit tidak disokong—sekatan ini disengajakan untuk mengelakkan ledakan gabungan pilihan.

Mengasingkan subagen secara automatik: isolation: worktree#

Apabila anda memberitahu Claude “lancarkan tiga subagen: seorang membaca pangkalan data, yang kedua meneliti API dan yang ketiga menyemak ujian,” ketiga-tiganya bekerja dalam salinan kerja anda secara lalai. Jika dua daripadanya menulis pada fail yang sama pada masa yang sama, konflik akan berlaku. Penyelesaiannya ialah memberikan setiap seorang worktree sendiri secara automatik.

Kaedah 1: minta secara lisan. Tulis kepada Claude dalam perbualan:

Gunakan worktree untuk agen anda.

Claude akan menggunakan pengasingan untuk semua subagen seterusnya dalam sesi ini.

Kaedah 2: tetapkan secara jelas dalam subagen itu sendiri. Dalam fail subagen (contohnya, .claude/agents/code-reviewer.md), tambahkan medan pada frontmatter:

---
name: code-reviewer
description: Reads the diff and writes code review comments
isolation: worktree
---

Anda seorang penyemak yang teliti. Baca diff dan cari ralat logik...

Kini setiap pelancaran subagen ini mendapat worktree sementara di .claude/worktrees/. Jika subagen tidak menulis apa-apa, folder itu dipadamkan secara automatik apabila ia selesai. Jika terdapat perubahan yang belum di-commit, Claude akan bertanya sama ada anda mahu menyimpan atau membuangnya.

Branch asas untuk worktree subagen sama seperti --worktree: secara lalai origin/HEAD; dengan worktree.baseRef: head, HEAD setempat.

Matriks keputusan: worktree, /bg, subagen atau Agent View#

Gabungan lazim:

• “2 ciri serentak, secara manual” — dua terminal, setiap satunya menjalankan claude --worktree. Kes paling mudah.
• “Mulakan pemfaktoran semula semalaman; saya akan menutup aplikasi” — /bg + /goal dengan syarat selesai. Sesi berjalan secara berasingan daripada tetingkap anda.
• “Satu prompt, tiga penyiasatan serentak” — tiga subagen dengan isolation: worktree. Setiap satu dalam ruang terasingnya sendiri.
• “Apa yang sedang berjalan sekarang?” — claude agents. Papan pemuka semua sesi dengan penapis “berjalan”, “disekat” dan “selesai”.

5 masalah lazim ketika bekerja dengan worktree#

1. Anda melancarkan worktree, .env tiada dan semuanya tidak berfungsi. Masalah paling lazim. Worktree ialah checkout baharu tanpa fail yang diabaikan Git. Penyelesaiannya ialah menambahkan fail .worktreeinclude dengan .env* dan konfigurasi setempat yang diperlukan sebaik sahaja anda menyediakan mod worktree. Pastikan fail itu berada di akar repositori, bukan dalam .claude/.

2. Anda mahu beralih ke branch utama, menjalankan cd ke akar dan kehilangan perubahan belum di-commit dalam worktree. Folder akar dan worktree ialah dua salinan kerja yang berbeza. Anda kembali dengan cd; perubahan dalam worktree kekal di situ—ia tidak ke mana-mana. Tetapi jika anda keliru lalu menjalankan git stash dalam folder utama kerana menyangka anda berada dalam worktree, stash itu akan dibuat pada branch utama, bukan branch yang anda jangkakan.

3. Anda melancarkan 5 sesi serentak dan tidak ingat lagi perkara yang sedang dilakukan setiap satu. Dokumentasi Anthropic memberi amaran secara jelas bahawa kebanyakan pembangun tidak mampu menguruskan lebih daripada 2–3 sesi dari segi kognitif. Tanda anda sudah terbeban ialah membuka Agent View dan tidak dapat menyatakan serta-merta perkara yang sedang dilakukan setiap agen. Hadkan diri kepada dua sesi serentak. Jika tugas memerlukan lebih banyak, orkestrakannya melalui /goal + subagen, bukan secara manual.

4. Worktree daripada -p (tanpa kepala) tidak dibersihkan secara automatik. Arahan claude --worktree feature-x -p "do thing" tidak memaparkan prompt keluar interaktif, maka tiada ketika Claude bertanya “buang worktree?”. Worktree ini akan terkumpul. Bersihkannya secara manual: git worktree remove .claude/worktrees/feature-x. Atau gunakan skrip cron yang membuang apa-apa yang lebih lama daripada 7 hari.

5. Dialog kepercayaan dalam folder baharu. Jika anda membuka repositori buat kali pertama lalu terus menjalankan claude --worktree, arahan itu akan gagal. Jalankan claude tanpa bendera, terima kepercayaan ruang kerja dan keluar—kemudian --worktree akan berfungsi. Ini disengajakan supaya Claude tidak mendapat akses kepada projek orang lain tanpa persetujuan pengguna.

Pembersihan: perkara yang dipadam secara automatik#

Logik pembersihan bergantung pada perkara yang anda lakukan dalam worktree dan cara anda memulakan sesi. Dokumentasi Anthropic menyenaraikan tiga senario:

Senario 1: anda masuk, tidak melakukan apa-apa dan keluar—worktree itu dibuang.

Senario 2: anda melakukan sedikit kerja tetapi tidak membuat commit—Claude akan bertanya “simpan atau buang?” apabila anda keluar. “Simpan” mengekalkan folder dan branch untuk digunakan kemudian. “Buang” memadam direktori bersama-sama perubahan belum di-commit dan commit baharu. Tindakan ini memusnahkan data—jangan klik “buang” kerana kebiasaan.

Senario 3: anda melancarkannya dengan -p (tanpa kepala), lalu arahan selesai dan keluar. Worktree itu kekal. Bersihkannya secara manual:

git worktree remove .claude/worktrees/feature-x

Selain itu, pembersihan latar belakang akan membuang worktree daripada subagen dan sesi /bg secara automatik jika worktree tersebut lebih lama daripada cleanupPeriodDays hari (tetapan yang lazimnya 30 hari secara lalai) dan tidak mengandungi kerja yang belum disimpan. Worktree daripada --worktree tidak disentuh oleh pembersihan automatik—tanggungjawab itu terletak pada anda.

Alternatif untuk SVN, Perforce dan Mercurial: hook WorktreeCreate#

Jika repositori menggunakan Subversion atau Mercurial, bendera --worktree tidak akan berfungsi secara langsung. Anthropic menyediakan titik sambungan melalui dua hook: WorktreeCreate (mencipta salinan terasing) dan WorktreeRemove (membuangnya).

Contoh hook SVN daripada dokumentasi rasmi:

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

Hook membaca nama worktree daripada stdin ({ "name": "feature-auth" }), menjalankan svn checkout ke direktori yang telah ditentukan dan mencetak laluan ke stdout—Claude Code menggunakannya sebagai direktori kerja untuk sesi baharu.

Perhatian penting: apabila menggunakan hook sendiri, .worktreeinclude tidak digunakan. Jika anda memerlukan .env atau fail lain yang diabaikan Git dalam folder baharu, salinnya dalam skrip hook itu sendiri.

Seterusnya: tiga mekanisme selari yang berkaitan#

Worktree memberikan pengasingan fail. /bg memberikan pengasingan konteks. Subagen memberikan pengasingan tugas. Setiap mekanisme menyelesaikan satu masalah secara tersendiri. Digabungkan, semuanya membolehkan anda mengusahakan tiga hingga lima tugas serentak tanpa kejatuhan kognitif. Inilah set kemahiran di sebalik vibe-coding lanjutan pada 2026.

Topik ini secara semula jadi bersambung kepada tiga perkara berkaitan: cara menyediakan agen autonomi menggunakan /goal dan Agent View, cara membina subagen sendiri untuk tugas anda dan cara melancarkan ratusan agen melalui Dynamic Workflows.

Buka Ailoot.