Cara Menggunakan Git Worktrees dengan Agen AI Coding

Arahkan dua agen coding AI ke checkout yang sama, dan pada akhirnya mereka akan merusak seluruh sore Anda. Satu agen menulis ulang file yang sedang diedit agen lain. Satu agen memindahkan branch yang sedang dipakai agen lain. Keduanya menjalankan npm install pada node_modules yang sama dan meninggalkan lockfile yang tidak ditulis oleh siapa pun. Kegagalannya berlangsung senyap sampai tiba-tiba tidak lagi, dan saat itu Anda harus melakukan bisect pada kekacauan yang tidak bisa dijelaskan oleh agen mana pun.

Git worktree adalah solusi standarnya. Worktree memberi setiap agen direktori kerja sendiri dan branch yang di-checkout sendiri di atas satu repositori bersama, sehingga pekerjaan paralel berhenti saling bertabrakan. Panduan ini membahas perintah-perintah nyatanya, jebakan yang benar-benar menggigit di praktik, dan disiplin pembersihan yang tidak pernah diberitahukan orang. Setelah itu, kita akan melihat di mana skrip worktree buatan sendiri berhenti berskala, dan bagaimana Sharkly menjalankan setiap Task di worktree-nya sendiri secara otomatis sehingga hasilnya kembali ke satu catatan bersama, bukan tersebar di berbagai terminal.

Jika Anda baru menjalankan satu agen, semua ini belum Anda butuhkan. Begitu Anda menjalankan dua, isolasi bukan lagi pilihan.

TL;DR

Git worktree adalah direktori kerja kedua yang terhubung ke repositori yang sama, dengan branch dan index-nya sendiri. Beri setiap agen coding AI worktree-nya sendiri, dan mereka bisa mengedit, build, serta test secara paralel tanpa saling menimpa atau berebut branch aktif. Perintahnya sederhana; yang terus bertambah adalah biaya operasionalnya (instalasi per worktree, pembersihan, disk, koordinasi). Sharkly mengelola biaya itu dengan menyiapkan worktree terisolasi untuk setiap Task secara otomatis dan mengembalikan setiap hasilnya ke Task tersebut untuk direview.

Mengapa satu checkout tidak bisa menampung dua agen

Checkout git biasa hanya memiliki satu direktori kerja, satu index, dan satu HEAD. Itu tidak masalah untuk satu orang yang mengerjakan satu hal. Semuanya berantakan begitu dua agen bekerja bersamaan, karena ketiganya merupakan state bersama.

Bayangkan dua agen di repositori yang sama. Agen A sedang merefaktor modul auth di branch bernama auth-refactor. Agen B diminta memperbaiki bug logging dan menjalankan git checkout -b fix-logging. Satu perintah itu memindahkan HEAD untuk seluruh checkout. Perubahan Agen A yang belum di-commit kini berada di atas branch yang salah, commit berikutnya mendarat di tempat yang keliru, dan build-nya mulai gagal karena alasan yang akan ia "debug" selama dua puluh menit. Tidak ada yang crash. State-nya hanya diam-diam menjadi salah.

Lebih buruk lagi soal file. Kedua agen berbagi satu direktori kerja, jadi ketika Agen B meregenerasi file config atau menjalankan ulang formatter, editan Agen A yang masih terbuka ditimpa di disk. Agen coding tidak punya model mental bahwa "yang lain sedang mengerjakan sesuatu." Mereka membaca file, bertindak, lalu menulisnya kembali. Dua penulis, satu file, tanpa lock. Anda mendapatkan masalah lost-update klasik, hanya saja penulisnya otonom dan cepat.

Inilah masalah yang terus muncul di balik kata kunci "git worktrees". Orang tidak mencari worktree karena branching itu menarik. Mereka mencari karena sudah pernah mencoba menjalankan agen secara paralel dan kena batunya. Jika itu Anda, sisi eksekusi paralelnya dibahas mendalam di panduan kami tentang menjalankan beberapa agen Claude Code secara paralel; artikel ini membahas primitif isolasi di bawahnya.

Apa sebenarnya git worktree itu

Berikut definisi yang layak dihafal:

Git worktree adalah direktori kerja tambahan yang terhubung ke repositori yang sama, dengan branch, index, dan HEAD yang di-checkout sendiri, serta berbagi satu object database.

Klausa terakhir itulah intinya. Worktree bukan clone. Clone menduplikasi seluruh object store: setiap commit, setiap blob, setiap tag disalin ke .git kedua. Worktree berbagi satu object store dan hanya menambahkan direktori kerja kedua yang ringan. Commit Anda langsung terlihat dari setiap worktree begitu dibuat, karena hanya ada satu riwayat di bawahnya. Yang berbeda di tiap worktree adalah checkout-nya: branch mana yang aktif, apa yang sudah di-stage, apa yang masih kotor di disk.

Untuk agen, ini memetakan dengan rapi ke masalahnya. Setiap agen mendapat satu worktree. Setiap worktree punya branch dan filenya sendiri. Mereka tidak bisa saling menimpa karena memang berada di direktori berbeda, dan tidak bisa menarik branch dari bawah kaki satu sama lain karena setiap worktree mematok HEAD-nya sendiri. Konflik berpindah ke tempat yang seharusnya: saat merge, secara sengaja, sambil direview—bukan di tengah pengeditan secara tidak sengaja.

Perintah worktree yang benar-benar akan Anda pakai

Mulailah di repositori biasa. Semua perintah di bawah ini dijalankan dari dalamnya.

Membuat worktree dengan branch baru. Ini yang paling sering Anda pakai:

git worktree add -b fix-logging ../myproject-fix-logging main

Perintah itu membuat direktori di ../myproject-fix-logging, membuat branch baru fix-logging yang dimulai dari main, dan melakukan checkout di sana. Arahkan agen ke direktori itu, dan ia punya tempat kerja yang bersih dan terisolasi.

Membuat worktree untuk branch yang sudah ada:

git worktree add ../myproject-auth auth-refactor

Melihat daftar worktree yang terbuka:

git worktree list

/Users/you/myproject              9f3c1a2 [main]
/Users/you/myproject-fix-logging  9f3c1a2 [fix-logging]
/Users/you/myproject-auth         3b7e0d4 [auth-refactor]

Satu baris per worktree, lengkap dengan path, commit yang di-checkout, dan branch-nya. Saat Anda menjalankan banyak agen, daftar ini adalah acuan utama untuk mengetahui siapa berada di mana.

Menghapus worktree ketika pekerjaannya sudah di-merge atau ditinggalkan:

git worktree remove ../myproject-fix-logging

Membersihkan metadata usang setelah Anda menghapus direktori worktree secara manual (agen dan skrip melakukannya lebih sering daripada yang Anda inginkan):

git worktree prune

Itulah keseluruhan cakupannya. Lima perintah. Kesulitannya bukan terletak pada perintahnya.

Jebakan yang benar-benar menggigit

Perintahnya sederhana. Realitas operasionalnya yang menghabiskan waktu. Berikut mode kegagalan yang muncul begitu agen sungguhan berjalan di worktree sungguhan.

File yang untracked dan masuk gitignore tidak ikut terbawa. Worktree melakukan checkout file yang terlacak pada branch yang Anda minta. Ia tidak menyalin node_modules, .env, venv, cache build, atau apa pun yang diabaikan git. Jadi worktree baru untuk proyek Node belum bisa dijalankan sampai Anda menjalankan install di dalamnya. Setiap worktree harus membayar sendiri instalasi dependency-nya, file environment-nya, dan build-nya. Agen yang mengasumsikan "repositori sudah siap" akan gagal pada perintah pertamanya di worktree baru sampai Anda menangani setup-nya secara eksplisit.

Anda tidak bisa melakukan checkout branch yang sama dua kali. Git menolak satu branch di-checkout di dua worktree sekaligus, dan itu memang benar. Jika dua agen sama-sama membutuhkan main dalam keadaan checkout, salah satunya harus membuat branch baru. Ini fitur, bukan keterbatasan, tetapi mengejutkan orang yang mengira worktree adalah salinan yang bebas berkeliaran.

Disk cepat penuh. Object storage dibagi, jadi riwayat itu murah. Direktori kerja beserta instalasinya tidak. Sepuluh worktree untuk proyek dengan node_modules berukuran 900 MB berarti 9 GB dependency yang terduplikasi. Di laptop yang menjalankan beberapa agen, Anda sudah merasakannya sebelum makan siang.

Worktree yang kotor menolak dihapus. git worktree remove akan menolak jika worktree memiliki perubahan yang belum di-commit, dan ini melindungi Anda dari membuang pekerjaan agen yang belum selesai. Ketika Anda benar-benar ingin menghapusnya, gunakan git worktree remove --force. Tapi sekarang Andalah yang harus memutuskan, satu per satu secara manual, apakah pekerjaan yang belum di-commit itu penting.

Direktori yang dihapus meninggalkan hantu. Hapus folder worktree dengan rm -rf, dan git masih mencantumkannya sampai Anda menjalankan git worktree prune. Skrip yang membuat worktree lebih cepat daripada membersihkannya akan menumpuk entri usang, dan entri-entri itu memegang lock yang menghalangi penggunaan ulang nama branch. Pembersihan bukan hal opsional; hanya saja mudah dilupakan sampai git worktree list berubah jadi pemakaman.

Cache agen yang bersarang bukan urusan Anda untuk dihapus. Sebagian runtime menyimpan cache worktree-nya sendiri, misalnya di bawah ~/.claude/worktrees. Jangan arahkan skrip pembersihan Anda ke sana. Biarkan tool yang memiliki cache itu yang mengelolanya.

Tidak ada satu pun yang sulit jika berdiri sendiri. Masalahnya, semuanya menumpuk. Dua worktree masih bisa Anda kelola manual. Lima, Anda menulis skrip. Dua belas agen berjalan di dua repositori, dan skrip itu kini menjadi infrastruktur kecil dengan bug-nya sendiri—dan Anda yang jadi penanggung jawabnya.

Di mana skrip berhenti berskala

Perjalanan jujurnya seperti ini. Anda mulai dengan fungsi shell yang membungkus git worktree add, menempatkan agen ke direktori baru, dan menjalankan setup. Berhasil. Anda menambahkan skema penamaan agar direktori tidak bertabrakan. Anda menambahkan perintah pembersihan. Lalu kebutuhan terus menumpuk.

Anda ingin tahu agen mana yang sedang berada di worktree mana, dan bagaimana status branch-nya. git worktree list tidak mengenal agen; ia hanya mengenal direktori. Anda menempelkan file pemetaan. Anda ingin instalasi dependency per worktree tidak menggilas disk Anda, jadi Anda menambahkan logika caching. Anda ingin output agen, diff-nya, dan hasil test-nya mendarat di tempat yang bisa direview manusia, bukan terjebak di terminal yang sudah ditutup. Sekarang Anda menulis pengumpul hasil. Anda ingin dua agen tidak sama-sama mengambil task yang sama dari antrean. Sekarang Anda menulis lock.

Pada titik tertentu, Anda sudah membangun ulang lapisan orkestrasi dari skrip shell, dan tidak ada yang bertanggung jawab memeliharanya. Inilah persisnya celah yang menjadi lahan perbincangan alternatif vibe kanban, dan inilah alasan tim beralih ke lapisan manajemen sungguhan begitu jumlah agen melewati ambang tertentu. Worktree bukanlah bagian yang sulit. Yang sulit adalah mengoordinasikan banyak eksekusi terisolasi dan mengembalikan hasilnya ke satu tempat.

Bagaimana Sharkly menjalankan setiap Task di worktree-nya sendiri

Sharkly adalah platform perintah dan manajemen Agent serba ada. Ia tidak menggantikan Claude Code, Codex, atau tool eksekusi lain yang sudah dipakai agen Anda; ia menambahkan lapisan Task, Computer, konteks, dan review bersama di sekitarnya. Isolasi worktree sudah tertanam di lapisan itu, jadi Anda tidak perlu lagi meraciknya sendiri.

Mekanismenya lugas. Setiap Task mendapat direktori terisolasi. Untuk pekerjaan berbasis repositori, Sharkly menyiapkan worktree baru setiap kali eksekusi dari data repositori yang di-cache, sehingga beberapa Task bisa bekerja pada sumber yang sama tanpa pernah menulis ke satu checkout bersama. Anda tidak menjalankan git worktree add. Anda tidak menulis skema penamaan, job pembersihan, atau file pemetaan. Anda menetapkan sebuah Task, dan isolasinya sudah tersedia.

Inilah pemisahan tanggung jawab yang membuat semuanya tenang. Agent menentukan bagaimana pekerjaan harus ditangani. Computer menyediakan host dan sumber daya lokal. Runtime menjalankan sesi agen yang sebenarnya. Task tetap menjadi catatan bersama untuk tim. Karena setiap eksekusi berada di worktree-nya sendiri, frontend, backend, perbaikan bug, dan cakupan test baru bisa bergerak bersamaan tanpa saling menginjak—persis paralelisme yang ingin dicapai pendekatan manual.

Dan hasilnya punya tempat untuk kembali. Eksekusi, blocker, hasil, dan diskusi lanjutan semuanya kembali ke timeline Task. Alih-alih diff agen tersimpan di terminal yang harus Anda ingat untuk dicek, ringkasan perubahan, output verifikasi, dan batasan yang diketahui kembali ke Task, tempat seseorang menerimanya, meminta perubahan, atau memutuskan merge. Konteks, progres, blocker, hasil, dan review manusia tetap terlihat dari permintaan sampai rilis, di satu tempat bersama alih-alih terpecah di prompt pribadi dan sesi terminal. Jika Anda baru dengan model ini, menetapkan Task pertama Anda ke agen coding AI adalah jalan masuk tercepat.

Anda tetap memakai tool yang sudah Anda gunakan. Penggunaan model tetap berjalan melalui langganan atau API key yang dikonfigurasi di tool tersebut; Sharkly menambahkan isolasi, koordinasi, dan review di sekitarnya.

Worktree manual versus lapisan manajemen

Kedua pendekatan memakai primitif yang sama. Bedanya, siapa yang menanggung beban operasionalnya.

Gunakan worktree manual ketika Anda seorang developer yang menjalankan satu atau dua agen dan ingin kontrol penuh atas shell. Setup itu benar-benar memadai, dan layak dipelajari karena mekanismenya mengajarkan Anda apa yang dilakukan lapisan di atasnya. Gunakan lapisan manajemen ketika jumlahnya bertambah, ketika lebih dari satu orang perlu melihat pekerjaannya, atau ketika kehilangan hasil agen di terminal yang tertutup benar-benar merugikan Anda. Ini sejalan dengan aturan keputusan jujur di panduan orkestrasi agen AI kami: jangan tambahkan mesin koordinasi sampai pekerjaan paralelnya nyata, dan jangan terus meraciknya sendiri setelah nyata.

Kontrak manusia-agen tetap berlaku

Isolasi mengubah di mana pekerjaan berlangsung, bukan siapa yang memutuskan. Worktree memungkinkan agen meneliti, mengeksekusi, menguji, dan melaporkan secara paralel tanpa tabrakan. Manusia tetap menetapkan arah, memberikan wewenang, dan menerima hasilnya. Otomasi berhenti di titik yang membutuhkan penilaian tim. Worktree baru untuk setiap agen itulah yang membuat batas tersebut dapat ditegakkan: pekerjaan tiap agen datang sebagai perubahan yang berbeda dan bisa direview di branch-nya sendiri, bukan sebagai editan tak terlacak yang tercampur ke checkout bersama. Anda mereview branch, bukan kekacauan. Untuk gambaran lebih luas tentang apa arti pergeseran ini dalam keseharian, penjelasan kami tentang agentic coding memberi konteksnya, dan What is Sharkly membahas platformnya secara menyeluruh.

Beberapa pendekatan terbukti untuk worktree manual

Jika untuk sekarang Anda tetap memilih cara manual, kebiasaan-kebiasaan ini mencegah sebagian besar masalahnya:

• Beri nama direktori worktree sesuai branch atau task, bukan berurutan. myproject-auth-refactor memberi tahu isinya; myproject-wt3 tidak.
• Simpan worktree sebagai sibling dari checkout utama, bukan bersarang di dalamnya. Penyarangan membingungkan tool yang menelusuri struktur direktori dan memperbesar aturan ignore Anda.
• Otomatiskan setup per worktree sebagai satu skrip yang dijalankan agen lebih dulu, sehingga worktree baru bisa langsung dijalankan dalam satu langkah alih-alih gagal karena instalasi yang belum ada.
• Lakukan prune sesuai jadwal, bukan saat ingat saja. git worktree prune harian plus peninjauan git worktree list akan menekan jumlah entri hantu.
• Jangan pernah menghapus cache runtime yang bersarang seperti ~/.claude/worktrees dari skrip Anda sendiri. Biarkan runtime yang memilikinya.
• Commit atau stash sebelum menghapus. --force ada untuk saat Anda benar-benar yakin, bukan sebagai default.

Kesimpulan

Git worktree adalah primitif isolasi yang membuat agen coding AI paralel menjadi aman. Ide-ide intinya layak diingat:

• Satu checkout hanya punya satu branch, satu index, satu HEAD, dan tidak bisa menampung dua agen sekaligus.
• Worktree menambahkan direktori kerja kedua di atas riwayat bersama yang sama, sehingga setiap agen mendapat branch dan file-nya sendiri.
• Kelima perintahnya (add, list, remove, prune, dan --force saat Anda memang berniat) sederhana.
• Biaya operasionalnya (instalasi per worktree, disk, pembersihan, koordinasi, pengumpulan hasil) yang terus bertambah.
• Worktree manual cocok untuk satu atau dua agen; lapisan manajemen mulai pantas digunakan seiring bertambahnya jumlah agen dan taruhannya.
• Sharkly menyiapkan worktree baru untuk setiap Task secara otomatis dan mengembalikan setiap hasilnya ke Task untuk direview manusia.

Pelajari dulu perintah manualnya; itu mengajarkan Anda apa yang dilakukan lapisan di atasnya. Ketika urusan pembukuan mulai lebih mahal daripada pekerjaannya, Sharkly mengambil alih worktree, koordinasi, dan review dari pundak Anda. Hubungkan satu Computer, buat satu Agent, dan beri ia tugas yang membosankan.

FAQ

Apa itu git worktree dalam istilah sederhana? Ini adalah direktori kerja kedua yang terhubung ke repositori yang sama, dengan branch yang di-checkout sendiri serta perubahan staged dan unstaged-nya sendiri. Ia berbagi satu riwayat commit dengan checkout utama, jadi jauh lebih ringan daripada clone. Untuk agen AI, artinya setiap agen mendapat tempat kerja privat tanpa menyentuh file milik agen lain.

Mengapa agen coding AI membutuhkan worktree? Karena dua agen yang berbagi satu checkout akan saling menimpa file dan mengubah branch satu sama lain. Satu worktree per agen memindahkan konflik ke waktu merge, saat konflik terlihat dan bisa direview, bukan ke tengah pengeditan, tempat konflik diam-diam merusak state. Lihat panduan kami tentang menjalankan beberapa agen Claude Code secara paralel untuk setup paralel selengkapnya.

Apakah worktree sama dengan clone? Tidak. Clone menyalin seluruh object database ke repositori terpisah. Worktree berbagi satu object database dan hanya menambahkan direktori kerja baru serta checkout branch. Commit yang dibuat di worktree mana pun langsung terlihat dari semuanya, dan penggunaan disknya jauh lebih rendah.

Bisakah dua worktree melakukan checkout branch yang sama? Tidak. Git menolak melakukan checkout satu branch di dua worktree sekaligus, untuk melindungi Anda dari penulisan yang saling bertentangan ke branch yang sama. Jika dua agen sama-sama membutuhkan branch itu sebagai basis, salah satunya harus membuat branch baru darinya.

Bagaimana cara membersihkan worktree dengan aman? Commit atau stash dulu semua pekerjaan, lalu git worktree remove <path>. Jika Anda menghapus direktori worktree secara manual, jalankan git worktree prune untuk membersihkan metadata usang. Jangan pernah mengarahkan skrip pembersihan ke cache milik runtime seperti ~/.claude/worktrees.

Kapan saya harus berhenti mengelola worktree secara manual? Ketika Anda mengoordinasikan lebih dari beberapa agen, ketika lebih dari satu orang perlu melihat pekerjaannya, atau ketika hasil yang hilang di terminal yang tertutup sudah memakan waktu Anda. Pada titik itu, lapisan manajemen yang mengisolasi dan melacak setiap eksekusi akan sepadan dengan biayanya. Panduan orkestrasi agen AI kami membahas kapan harus mengambil lompatan itu.