Worktree
Worktree
Gunakan Git worktree di Codex dalam aplikasi desktop ChatGPT untuk menjalankan obrolan secara paralel
Worktree memungkinkan Codex menjalankan beberapa percakapan independen dalam proyek yang sama tanpa saling mengganggu. Repositori, worktree, dan perintah tetap berada di komputer atau lingkungan pengembangan jarak jauh yang memuat proyek tersebut. Anda dapat bekerja langsung di aplikasi desktop ChatGPT, atau menggunakan Remote di aplikasi seluler ChatGPT untuk memulai, memandu, menyetujui, dan meninjau percakapan worktree di komputer yang terhubung.
Untuk repositori Git, tugas terjadwal dapat dijalankan di worktree latar belakang khusus agar tidak berkonflik dengan pekerjaan yang sedang berlangsung. Dalam proyek tanpa kontrol versi, tugas terjadwal dijalankan langsung di direktori proyek. Anda juga dapat memulai percakapan di worktree secara manual dan menggunakan Handoff untuk memindahkan percakapan antara Local dan Worktree.
Apa itu worktree
Worktree hanya berfungsi dalam proyek yang merupakan bagian dari repositori Git karena menggunakan Git worktree sebagai mekanisme dasarnya. Worktree memungkinkan Anda membuat salinan kedua ("checkout") repositori. Setiap worktree memiliki salinan tersendiri untuk setiap file dalam repo Anda, tetapi semuanya berbagi metadata yang sama (folder .git) mengenai commit, branch, dan sebagainya. Dengan demikian, Anda dapat melakukan checkout dan mengerjakan beberapa branch secara paralel.
Terminologi
- Checkout lokal: Repositori yang Anda buat. Terkadang hanya disebut sebagai Local dalam aplikasi desktop ChatGPT.
- Worktree: Git worktree yang dibuat dari checkout lokal Anda dalam aplikasi desktop ChatGPT.
- Handoff: Alur yang memindahkan obrolan antara Local dan Worktree. Codex menangani operasi Git yang diperlukan untuk memindahkan pekerjaan Anda di antara keduanya dengan aman.
Alasan menggunakan worktree
- Bekerja secara paralel dengan Codex tanpa mengganggu penyiapan Local Anda saat ini.
- Mengantrekan pekerjaan latar belakang sementara Anda tetap berfokus pada pekerjaan utama.
- Memindahkan obrolan ke Local nanti saat Anda siap memeriksa, menguji, atau berkolaborasi secara lebih langsung.
Memulai
Worktree memerlukan repositori Git. Pastikan proyek yang Anda pilih berada di dalam repositori Git.
Pilih "Worktree"
Dalam tampilan obrolan baru, pilih Worktree di bawah kotak penulisan. Jika perlu, pilih lingkungan lokal untuk menjalankan skrip penyiapan bagi worktree.
Pilih branch awal
Di bawah kotak penulisan, pilih branch Git yang akan menjadi dasar worktree. Branch ini dapat berupa branch
main/master, branch fitur, atau branch Anda saat ini dengan perubahan lokal yang belum di-stage.Kirim prompt Anda
Kirim prompt Anda, lalu Codex membuat Git worktree berdasarkan branch yang Anda pilih. Secara default, Codex bekerja dalam keadaan "detached HEAD".
Pilih tempat untuk melanjutkan pekerjaan
Saat siap, Anda dapat terus bekerja langsung dalam worktree atau menyerahkan obrolan ke checkout lokal. Melakukan handoff ke atau dari Local akan memindahkan obrolan dan kode Anda sehingga Anda dapat melanjutkan di checkout lainnya.
Bekerja antara Local dan Worktree
Tampilan dan cara kerja worktree sangat mirip dengan checkout lokal Anda. Perbedaannya terletak pada posisinya dalam alur kerja Anda. Anda dapat menganggap Local sebagai lingkungan utama dan Worktree sebagai lingkungan latar belakang. Handoff memungkinkan Anda memindahkan obrolan di antara keduanya.
Di balik layar, Handoff menangani operasi Git yang diperlukan untuk memindahkan pekerjaan secara aman di antara dua checkout. Hal ini penting karena Git hanya mengizinkan suatu branch di-checkout di satu tempat pada satu waktu. Jika Anda melakukan checkout suatu branch dalam worktree, Anda tidak dapat melakukan checkout branch tersebut dalam checkout lokal secara bersamaan, dan sebaliknya.
Dalam praktiknya, terdapat dua alur umum:
- Bekerja secara eksklusif dalam worktree. Alur ini paling sesuai jika Anda dapat memverifikasi perubahan langsung dalam worktree, misalnya karena Anda telah menginstal dependensi dan alat menggunakan skrip penyiapan lingkungan lokal.
- Menyerahkan obrolan ke Local. Gunakan alur ini saat Anda ingin membawa obrolan ke lingkungan utama, misalnya karena Anda ingin memeriksa perubahan dalam IDE yang biasa digunakan atau hanya dapat menjalankan satu instans aplikasi Anda.
Opsi 1: Bekerja dalam worktree
Jika Anda ingin tetap bekerja secara eksklusif dalam worktree beserta perubahan Anda, ubah worktree menjadi branch menggunakan tombol Buat branch di sini pada header obrolan.
Dari sini, Anda dapat melakukan commit atas perubahan, mendorong branch ke repositori jarak jauh, dan membuka pull request di GitHub.
Anda dapat membuka IDE ke worktree menggunakan tombol "Buka" di header, menggunakan terminal terintegrasi, atau melakukan hal lain yang diperlukan dari direktori worktree.
Opsi 2: Menyerahkan obrolan ke Local
Jika Anda ingin membawa obrolan ke lingkungan utama, pilih Serahkan pada header obrolan lalu pindahkan ke Lokal.
Alur ini sesuai ketika Anda ingin membaca perubahan dalam jendela IDE yang biasa digunakan, menjalankan server pengembangan yang sudah ada, atau memvalidasi pekerjaan dalam lingkungan yang Anda gunakan sehari-hari.
Codex menangani langkah Git yang diperlukan untuk memindahkan obrolan secara aman antara worktree dan checkout lokal Anda.
Setiap obrolan tetap terkait dengan worktree yang sama dari waktu ke waktu. Jika nanti Anda menyerahkan kembali obrolan tersebut ke worktree, Codex akan mengembalikannya ke lingkungan latar belakang yang sama sehingga Anda dapat melanjutkan dari bagian terakhir.
Karena Handoff menggunakan operasi Git, file apa pun yang menjadi bagian dari file .gitignore Anda tidak akan ikut berpindah bersama obrolan kecuali Codex menyalinnya ke worktree lokal terkelola dengan .worktreeinclude.
Detail lanjutan
Worktree yang dikelola Codex dan worktree permanen
Secara default, obrolan menggunakan worktree yang dikelola Codex. Worktree ini dirancang agar ringan dan dapat dibuang. Worktree yang dikelola Codex biasanya dikhususkan untuk satu obrolan, dan Codex mengembalikan obrolan tersebut ke worktree yang sama jika nanti Anda menyerahkannya kembali ke sana.
Jika menginginkan lingkungan berumur panjang, buat worktree permanen dari menu tiga titik pada proyek di bilah samping. Tindakan ini membuat worktree permanen baru sebagai proyek tersendiri. Worktree permanen tidak dihapus secara otomatis, dan Anda dapat memulai beberapa obrolan dari worktree yang sama.
Cara Codex mengelola worktree untuk Anda
Codex membuat worktree di $CODEX_HOME/worktrees. Commit awalnya adalah commit HEAD dari cabang yang dipilih saat Anda memulai obrolan. Jika Anda memilih cabang yang memiliki perubahan lokal, Codex juga menerapkan perubahan yang belum di-commit ke worktree. Worktree tersebut tidak di-checkout sebagai cabang. Worktree berada dalam status detached HEAD. Dengan demikian, Codex dapat membuat beberapa worktree tanpa mengotori cabang Anda.
Menyalin file lokal yang diabaikan ke worktree terkelola
Worktree lokal yang dikelola Codex dimulai dari checkout Git, sehingga file yang dilacak sudah tersedia. Jika repositori Anda mengabaikan file penyiapan lokal yang diperlukan worktree baru, tambahkan file .worktreeinclude ke root repositori dan cantumkan jalur yang diabaikan atau pola bergaya .gitignore yang akan disalin ketika Codex membuat worktree terkelola.
Gunakan fitur ini untuk file yang sengaja diabaikan Git, seperti .env, .env.local, atau config/secrets.json. Codex hanya menyalin file yang diabaikan dan cocok dengan .worktreeinclude; Codex tidak menyalin file lokal lain yang tidak dilacak Git. Jangan cantumkan file yang dilacak.
Codex secara otomatis menyalin AGENTS.override.md yang diabaikan ke worktree lokal terkelola, sehingga Anda tidak perlu mencantumkannya dalam .worktreeinclude.
# .worktreeinclude
.env
.env.local
config/secrets.jsonCodex melewati symlink sumber dan tidak akan menimpa file yang sudah ada dalam checkout baru. Perilaku ini berlaku untuk worktree lokal terkelola aplikasi desktop ChatGPT, bukan worktree jarak jauh atau Git worktree yang Anda buat sendiri dari baris perintah.
Batasan branch
Misalkan Codex menyelesaikan suatu pekerjaan dalam worktree dan Anda memilih untuk membuat branch feature/a di dalamnya menggunakan Create branch here. Sekarang, Anda ingin mencobanya dalam checkout lokal. Jika mencoba melakukan checkout branch tersebut, Anda akan menerima kesalahan berikut:
fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'Untuk mengatasinya, Anda perlu melakukan checkout branch lain, bukan feature/a, dalam worktree.
Jika Anda berencana melakukan checkout branch secara lokal, gunakan Handoff untuk memindahkan obrolan ke Local, bukan mencoba mempertahankan branch yang sama agar di-checkout di kedua tempat secara bersamaan.
Mengapa batasan ini ada
Git mencegah cabang yang sama di-checkout di lebih dari satu worktree pada saat yang sama karena cabang merepresentasikan satu referensi yang dapat diubah (`refs/heads/Ketika suatu branch di-checkout, Git memperlakukan HEAD-nya sebagai milik worktree tersebut dan mengharapkan operasi seperti commit, reset, rebase, dan merge untuk memajukan referensi itu dengan cara yang terdefinisi dengan baik dan berurutan. Mengizinkan beberapa worktree melakukan checkout branch yang sama secara bersamaan akan menimbulkan ambiguitas dan kondisi balapan mengenai operasi worktree mana yang memperbarui referensi branch, yang berpotensi menyebabkan commit hilang, indeks tidak konsisten, atau penyelesaian konflik yang tidak jelas.
Dengan memberlakukan aturan satu branch per worktree, Git menjamin bahwa setiap branch memiliki satu salinan kerja otoritatif, sekaligus tetap memungkinkan worktree lain mereferensikan commit yang sama secara aman melalui detached HEAD atau branch terpisah.
Pembersihan worktree
Worktree dapat menggunakan banyak ruang disk. Masing-masing memiliki kumpulan file repositori, dependensi, cache build, dan sebagainya sendiri. Karena itu, aplikasi desktop ChatGPT berupaya mempertahankan jumlah worktree dalam batas yang wajar.
Secara default, Codex mempertahankan 15 worktree terkelola Codex terbaru. Anda dapat mengubah batas ini atau menonaktifkan penghapusan otomatis dalam pengaturan jika lebih suka mengelola penggunaan disk sendiri.
Codex berupaya menghindari penghapusan worktree yang masih penting. Worktree yang dikelola Codex tidak akan dihapus secara otomatis jika:
- Obrolan yang disematkan terkait dengannya
- Obrolan masih berlangsung
- Worktree tersebut merupakan worktree permanen
Worktree yang dikelola Codex dihapus secara otomatis ketika:
- Anda mengarsipkan obrolan terkait
- Codex perlu menghapus worktree lama agar tetap berada dalam batas yang Anda konfigurasi
Sebelum menghapus worktree yang dikelola Codex, Codex menyimpan snapshot pekerjaan di dalamnya. Jika Anda membuka obrolan setelah worktree-nya dihapus, Anda akan melihat opsi untuk memulihkannya.