Skip to main content

Worktrees

ใน Codex App worktrees ให้ Codex รันงานอิสระหลายงานในโปรเจกต์เดียวกันโดยไม่กระทบซึ่งกันและกัน สำหรับ Git repositories automations รันบน background worktrees เฉพาะ สำหรับโปรเจกต์ที่ไม่ได้ใช้ version control automations รันตรงในโฟลเดอร์โปรเจกต์

Worktree คืออะไร​

Worktrees ทำงานเฉพาะกับโปรเจกต์ที่เป็นส่วนหนึ่งของ Git repository เนื่องจากใช้ Git worktrees เป็นพื้นฐาน

Worktree ให้คุณสร้าง "สำเนาที่สอง" (checkout) ของ repository แต่ละ worktree มีสำเนาของทุกไฟล์ใน repo แต่ทั้งหมดแชร์ metadata เดียวกัน (โฟลเดอร์ .git) ซึ่งทำให้ checkout และทำงานบน branches หลายอันพร้อมกันได้

คำศัพท์​

  • Local checkout: Repository ที่คุณสร้าง บางครั้งเรียกแค่ว่า Local ใน Codex App
  • Worktree: Git worktree ที่สร้างจาก local checkout ใน Codex App
  • Handoff: Flow ที่ย้าย thread ระหว่าง Local และ Worktree Codex จัดการ Git operations ที่จำเป็นเพื่อย้ายงานได้อย่างปลอดภัย

ทำไมต้องใช้ worktree​

  • ทำงานแบบขนานกับ Codex โดยไม่กระทบ Local setup ปัจจุบัน
  • คิว background work ขณะที่คุณมุ่งเน้น foreground
  • ย้าย thread ไปยัง Local ในภายหลังเมื่อพร้อม inspect, ทดสอบ หรือ collaborate โดยตรง

เริ่มต้นใช้งาน​

เลือก Worktree​

ใน new thread view เลือก Worktree ใต้ composer เลือก local environment เพื่อรัน setup scripts สำหรับ worktree หากต้องการ

เลือก starting branch​

ด้านล่าง composer เลือก Git branch เพื่อเป็นฐานของ worktree ซึ่งอาจเป็น main/master branch, feature branch หรือ branch ปัจจุบันที่มี unstaged local changes

ส่ง prompt​

ส่งงานของคุณและ Codex จะสร้าง Git worktree ตาม branch ที่เลือก โดยค่าเริ่มต้น Codex ทำงานใน "detached HEAD"

เลือกว่าจะทำงานต่อที่ไหน​

เมื่อพร้อม คุณสามารถทำงานต่อบน worktree โดยตรงหรือ hand thread off ไปยัง local checkout

ทำงานระหว่าง Local และ Worktree​

คิดถึง Local เป็น foreground และ Worktree เป็น background Handoff ให้คุณย้าย thread ระหว่างกัน

มีสองเส้นทางทั่วไป:

ตัวเลือกที่ 1: ทำงานบน worktree​

หากต้องการอยู่บน worktree กับการเปลี่ยนแปลง ให้แปลง worktree เป็น branch โดยใช้ปุ่ม Create branch here ใน header ของ thread จากนั้น commit การเปลี่ยนแปลง, push branch ไปยัง remote และเปิด PR บน GitHub

ตัวเลือกที่ 2: Hand off thread ไปยัง Local​

คลิก Hand off ใน thread header และย้ายไปยัง Local เส้นทางนี้ดีเมื่อต้องการอ่านการเปลี่ยนแปลงใน IDE ปกติ, รัน development server ที่มีอยู่ หรือ validate งานในสภาพแวดล้อมที่ใช้ประจำ

รายละเอียดขั้นสูง​

Codex-managed และ permanent worktrees​

โดยค่าเริ่มต้น threads ใช้ Codex-managed worktree ซึ่งออกแบบมาให้เบาและใช้แล้วทิ้ง Codex-managed worktree มักอุทิศให้กับ thread เดียว

หากต้องการสภาพแวดล้อมระยะยาว ให้สร้าง permanent worktree จาก three-dot menu บน project ใน sidebar Permanent worktrees ไม่ถูกลบโดยอัตโนมัติ และคุณสามารถเริ่ม threads หลายอันจาก worktree เดิมได้

วิธี Codex จัดการ worktrees​

Codex สร้าง worktrees ใน $CODEX_HOME/worktrees starting commit จะเป็น HEAD commit ของ branch ที่เลือกเมื่อเริ่ม thread Worktree จะไม่ถูก checkout เป็น branch แต่จะอยู่ใน detached HEAD state

Copy ignored local files เข้า managed worktrees​

หาก repository มี local setup files ที่ถูก ignore และ worktree ใหม่ต้องการ ให้เพิ่มไฟล์ .worktreeinclude ที่ repository root และแสดงรายการ ignored paths ที่ต้องการ copy

ใช้สำหรับไฟล์ที่ Git ตั้งใจ ignore เช่น .env, .env.local หรือ config/secrets.json

ตัวอย่าง .worktreeinclude:

.env
.env.local
config/secrets.json

Codex จะ copy AGENTS.override.md ที่ถูก ignore เข้า managed worktrees โดยอัตโนมัติ ไม่ต้องแสดงรายการใน .worktreeinclude

Branch limitations​

หาก Codex สร้าง branch feature/a บน worktree และคุณพยายาม checkout บน local checkout จะได้ error:

fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'

Git ป้องกัน branch เดียวกันจากการ checkout ใน worktrees หลายอันพร้อมกัน

เพื่อแก้ปัญหา ใช้ Handoff เพื่อย้าย thread ไปยัง Local แทนที่จะพยายาม checkout branch เดิมในทั้งสองที่พร้อมกัน

Worktree cleanup​

Worktrees อาจใช้พื้นที่ disk จำนวนมาก โดยค่าเริ่มต้น Codex เก็บ Codex-managed worktrees ล่าสุด 15 อัน คุณสามารถเปลี่ยน limit นี้หรือปิดการลบอัตโนมัติใน settings

Codex พยายามหลีกเลี่ยงการลบ worktrees ที่ยังสำคัญ Codex-managed worktrees จะ ไม่ ถูกลบอัตโนมัติหาก:

  • conversation ที่ pin ไว้เชื่อมต่อกับมัน
  • thread ยังดำเนินอยู่
  • เป็น permanent worktree

Codex-managed worktrees จะถูกลบอัตโนมัติเมื่อ:

  • คุณ archive thread ที่เกี่ยวข้อง
  • Codex ต้องลบ worktrees เก่าเพื่อให้อยู่ใน limit ที่กำหนด

ก่อนลบ Codex-managed worktree Codex จะบันทึก snapshot ของงาน หากเปิด conversation หลังจาก worktree ถูกลบ คุณจะเห็นตัวเลือก restore

คำถามที่พบบ่อย​

ฉันสามารถควบคุมว่า worktrees ถูกสร้างที่ไหนได้ไหม? ยังไม่ได้ในขณะนี้ Codex สร้าง worktrees ใต้ $CODEX_HOME/worktrees

ฉันสามารถย้าย thread ระหว่าง Local และ Worktree ได้ไหม? ได้ ใช้ Hand off ใน thread header Codex จัดการ Git operations ที่จำเป็น

เกิดอะไรขึ้นกับ threads หาก worktree ถูกลบ? Threads สามารถยังอยู่ใน history ได้แม้ว่า worktree directory จะถูกลบ สำหรับ Codex-managed worktrees Codex บันทึก snapshot ก่อนลบและเสนอ restore เมื่อเปิด thread ที่เกี่ยวข้อง Permanent worktrees ไม่ถูกลบโดยอัตโนมัติเมื่อ archive threads