Git worktree ใน Claude Code: เซสชันคู่ขนาน

ข้อมูลเชิงปฏิบัติเกี่ยวกับการใช้งาน Ailoot อยู่ในเอกสารประกอบ.

git worktree ใน Claude Code คืออะไร#

การเปิดเอเจนต์หลายตัวพร้อมกันในโฟลเดอร์เดียวกันคือปัญหาพื้นฐานของ vibe-coding ด้วยความเร็วระดับปี 2026 AI agent เขียนโค้ดเร็วกว่าที่คนจะติดตามได้ว่าใครกำลังแก้ไขอะไร หากไม่มีการแยกไฟล์ การเปิด Claude Code สองเซสชันพร้อมกันในไดเรกทอรีเดียวกันจะจบลงด้วยเซสชันหนึ่งเขียนทับงานของอีกเซสชัน

Git worktree แก้ปัญหานี้ในระดับระบบไฟล์ คุณมีไดเรกทอรีหลักหนึ่งแห่งสำหรับทำงาน คำสั่ง claude --worktree feature-auth จะสร้างโฟลเดอร์ .claude/worktrees/feature-auth/ บน branch แยกและเริ่ม Claude Code ที่นั่น ไฟล์ถูกแยกจากกัน การเปลี่ยนแปลงในเซสชันหนึ่งจะไม่ปรากฏในอีกเซสชันจนกว่าคุณจะ merge เข้าด้วยกันอย่างชัดเจน

เอกสารทางการของ Anthropic อธิบายไว้ดังนี้:

ข้อบ่งชี้สำหรับตรวจสอบตัวเอง: หากคุณเคยได้ commit ที่มีไฟล์ครึ่งหนึ่งเป็นงานของคนอื่น คุณก็ต้องใช้ worktree

git worktree แตกต่างจาก branch ปกติอย่างไร#

ขั้นตอน Git แบบมาตรฐาน: คุณอยู่บน branch main แล้วรัน git checkout feature-x — Git จะเขียนทับไฟล์ในสำเนาทำงาน กระบวนการ npm run dev ที่กำลังทำงานอยู่พัง เพราะ package.json เปลี่ยนไปขณะที่โปรแกรมกำลังทำงาน คุณ stash การเปลี่ยนแปลงที่ยังไม่ได้ commit และรอให้ IDE ทำดัชนีใหม่ จากนั้นสลับกลับ ทุกอย่างก็ถูกเขียนทับอีก จึงต้อง stash และ pop อีกครั้ง

Git worktree ให้ทางเลือกอีกแบบ: แทนที่จะสลับ branch ในโฟลเดอร์ เดียว ให้สร้าง โฟลเดอร์ที่สอง สำหรับอีก branch คำสั่ง git worktree add ../project-feature-x feature-x สร้างไดเรกทอรี ../project-feature-x/ พร้อมไฟล์จาก branch feature-x โดย main ยังคงอยู่ในโฟลเดอร์เดิม และเซิร์ฟเวอร์ dev ก็ทำงานต่อไป

ก่อนหน้านี้ต้องตั้งค่าโหมด worktree ใน Claude Code ด้วยตนเอง: git worktree add จากนั้น cd แล้วจึง claude และต้องทำซ้ำในทุกเทอร์มินัล แฟล็ก --worktree (หรือ -w) ทำทั้งสามขั้นตอนด้วยคำสั่งเดียว

เริ่มเซสชันคู่ขนานเซสชันแรก: แฟล็ก --worktree#

ตัวอย่างขั้นต่ำ เปิดเทอร์มินัลแรกที่ root ของโปรเจกต์:

claude --worktree feature-auth

Claude Code ทำสามอย่าง:

1. สร้าง .claude/worktrees/feature-auth/ พร้อม snapshot ของ origin/HEAD (โดยปกติคือ branch เริ่มต้นของคุณ)
2. สร้าง branch ใหม่ชื่อ worktree-feature-auth
3. เริ่มเซสชันในโฟลเดอร์นี้

เปิดเทอร์มินัลที่สองในโฟลเดอร์ root เดียวกันของ repository:

claude --worktree bugfix-123

เรียบร้อย มี Claude Code สองเซสชัน ไฟล์คนละชุดบนดิสก์ และ Git branch คนละอัน หากคุณเขียนระบบยืนยันตัวตนในเซสชันแรกและแก้การทดสอบที่ล้มเหลวในเซสชันที่สอง ทั้งสองจะไม่มีทางรบกวนกันทางกายภาพ

หากไม่อยากพิมพ์ชื่อ Claude จะคิดชื่อขึ้นมาให้:

claude --worktree
# → creates something like .claude/worktrees/bright-running-fox/

เคล็ดลับสำหรับผู้เริ่มต้นใช้ Git: เพิ่ม .claude/worktrees/ ลงใน .gitignore มิฉะนั้นเมื่อรัน git status ในโฟลเดอร์หลัก คุณจะเห็นเนื้อหาของ worktree ทั้งหมดเป็นไฟล์ที่ยังไม่ถูกติดตาม:

# .gitignore
.claude/worktrees/

ข้อผิดพลาดที่ควรหลีกเลี่ยง: ก่อนเรียกใช้ --worktree ครั้งแรกในไดเรกทอรีใหม่ ให้เข้าไปด้วย claude แบบปกติ (ไม่มีแฟล็ก) และยอมรับกล่องโต้ตอบความเชื่อถือของ workspace หากไม่ทำเช่นนั้น แฟล็กจะล้มเหลวด้วยข้อผิดพลาด “trust not accepted” รวมถึงกรณีใช้ร่วมกับ -p สำหรับโหมด headless

worktree อยู่ที่ไหนและค้นหาได้อย่างไร#

ตำแหน่งเริ่มต้นถูกกำหนดไว้ตายตัว: .claude/worktrees/<value>/ ที่ root ของ repository หากโปรเจกต์อยู่ใน ~/dev/my-app/ worktree ของ feature-auth จะอยู่ที่ ~/dev/my-app/.claude/worktrees/feature-auth/

สำหรับโครงสร้างที่ไม่เป็นมาตรฐาน (เช่น หากต้องการให้ worktree อยู่นอก repository) มี hook WorktreeCreate ซึ่งจะกล่าวถึงเพิ่มเติมด้านล่างในหัวข้อ SVN และ Mercurial

ภายในเซสชัน Claude หนึ่งเซสชัน คุณสามารถสลับไปยัง worktree อื่นที่มีอยู่แล้วได้ เพียงพิมพ์ในแชตว่า “switch to .claude/worktrees/bugfix-123” แล้ว Claude จะเรียกใช้เครื่องมือ EnterWorktree โฟลเดอร์ปัจจุบันจะยังคงเดิม และคุณกลับไปได้ด้วยวิธีเดียวกัน

คำสั่ง Git มาตรฐานแสดงรายการ worktree ทั้งหมด รวมถึง worktree หลักและ worktree ที่สร้างด้วยตนเอง:

git worktree list

ผลลัพธ์จะมีลักษณะดังนี้:

/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]

คัดลอก .env และข้อมูลลับ: ไฟล์ .worktreeinclude#

เมื่อ --worktree สร้างโฟลเดอร์ใหม่ ก็จะได้รับเฉพาะสิ่งที่ commit ไว้ใน Git เท่านั้น .env ที่มี API key และ .env.local ที่มีการกำหนดค่าในเครื่องอยู่ใน .gitignore จึงไม่อยู่ใน worktree และเมื่อรัน npm run dev ครั้งแรกก็ล้มเหลวด้วย “MISSING DATABASE_URL.”

วิธีแก้แบบทำเองคือคัดลอก .env ด้วยตนเองหลังใช้ --worktree ทุกครั้ง วิธีนี้ใช้ได้ครั้งหนึ่ง แล้วก็ลืมทำ วิธีของ Anthropic คือสร้างไฟล์ .worktreeinclude ที่ root ของโปรเจกต์ แล้วระบุไฟล์ที่ Git ไม่ติดตามเพื่อให้คัดลอกไปยัง worktree ใหม่แต่ละแห่งโดยอัตโนมัติ

สร้างไฟล์ .worktreeinclude ที่ root ของ repository:

.env
.env.local
config/secrets.json

ไวยากรณ์เหมือนกับ .gitignore สามารถใช้รูปแบบ glob ได้:

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

Anthropic ให้กฎที่ชัดเจนเพื่อป้องกันอุบัติเหตุ:

กล่าวอีกอย่างคือ คุณไม่สามารถคัดลอก package.json โดยไม่ตั้งใจผ่าน .worktreeinclude ได้ เพราะไฟล์นี้ไม่ได้อยู่ใน .gitignore จึงใส่รูปแบบใด ๆ ไว้ตรงนั้นได้อย่างปลอดภัย

.worktreeinclude เดียวกันใช้ได้ในสามโหมด: --worktree แบบกำหนดเอง, worktree อัตโนมัติสำหรับ subagent (ดูด้านล่าง) และเซสชันจากแอปเดสก์ท็อป Claude

สร้าง worktree จาก pull request เพื่อรีวิวโค้ด#

สถานการณ์รีวิวโค้ดทั่วไป: เพื่อนร่วมงานส่ง PR มา คุณต้องตรวจโค้ด รันการทดสอบ และเขียนความคิดเห็น หากใช้ git checkout pull/1234/head แบบปกติ คุณจะสลับสำเนาทำงานอีกครั้งและทำให้เซสชันที่กำลังใช้งานอยู่เสียหาย

ใช้แฟล็ก --worktree แล้วทำได้ด้วยคำสั่งเดียว:

claude --worktree "#1234"

สิ่งที่จะเกิดขึ้น: Claude Code รัน git fetch origin pull/1234/head สร้าง worktree ที่ .claude/worktrees/pr-1234/ และ checkout branch ของ PR จากนั้นเซสชันจะเริ่มทำงาน คุณสามารถขอให้มัน “read the diff, run the tests, and find logical errors” ได้ทันที ขณะที่ Claude ทำงาน เซสชันหลักของคุณบน main ก็ยังทำงานต่อไป

ไวยากรณ์อีกแบบคือ URL เต็มของ pull request:

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

การใช้งานในโปรเจกต์จริง: เมื่อนำ claude --worktree "#N" มารวมกับ subagent สำหรับรีวิวโค้ดของคุณ ก็จะได้รีวิวอัตโนมัติภายในหนึ่งหรือสองนาที เปิดใช้งานไว้เบื้องหลัง ทำงานต่อในหน้าต่างหลัก แล้วกลับมาดูผลผ่าน claude agents

Branch ฐาน: worktree.baseRef สำหรับ fresh หรือ head#

ค่าเริ่มต้นคือ worktree ใหม่ทุกแห่งเริ่มจาก origin/HEAD ข้อดีคือได้จุดเริ่มต้นที่สะอาดและรับรองได้ว่าจะตรงกับสิ่งที่ CI จะเห็น ข้อเสียคือหากคุณมีการเปลี่ยนแปลงที่ยังไม่ได้ commit หรือมี commit ในเครื่องหลายรายการเกินกว่า remote บน branch ปัจจุบัน สิ่งเหล่านั้นจะไม่รวมอยู่ใน worktree ใหม่

หากต้องการเริ่ม worktree จาก HEAD commit ปัจจุบันในเครื่อง ให้เพิ่มใน .claude/settings.json หรือค่าทั่วไป:

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

ตอนนี้ claude --worktree experimental-feature เริ่มจาก HEAD ในเครื่องปัจจุบัน เหมาะเมื่อฟีเจอร์มี commit ในเครื่องที่ยังไม่ push ไม่รวม tracked edits ที่ยังไม่ commit หากซับเอเจนต์ต้องใช้ ให้เก็บและโอนการแก้ที่จำเป็นชัดเจน แล้วตรวจ diff ปลายทาง อย่าสับสนการโอนนี้กับ .worktreeinclude ซึ่งจัดการไฟล์ในเครื่องที่ ignore

การตั้งค่านี้รับค่าได้ตรงตัวเพียงสองค่า: "fresh" (= origin/HEAD) และ "head" (= local HEAD) ไม่รองรับ ref ตามอำเภอใจ เช่น "feature-branch" หรือ hash ของ commit ซึ่งเป็นข้อจำกัดโดยตั้งใจเพื่อป้องกันไม่ให้ตัวเลือกเพิ่มขึ้นอย่างไร้ขอบเขต

แยก subagent โดยอัตโนมัติ: isolation: worktree#

เมื่อคุณบอก Claude ว่า “launch three subagents: one reads the database, the second looks at the API, and the third checks the tests” ทั้งสามตัวจะทำงานในสำเนาทำงานของคุณโดยค่าเริ่มต้น หากมีแม้แต่สองตัวเขียนไฟล์เดียวกันในเวลาเดียวกัน ก็จะเกิดความขัดแย้ง วิธีแก้คือให้แต่ละตัวมี worktree ของตัวเองโดยอัตโนมัติ

วิธีที่ 1: ขอด้วยคำพูด เขียนถึง Claude ในบทสนทนา:

Use worktrees for your agents.

Claude จะใช้ isolation กับ subagent ทุกตัวที่เปิดหลังจากนั้นในเซสชันนี้

วิธีที่ 2: กำหนดไว้อย่างชัดเจนใน subagent เอง ในไฟล์ subagent (เช่น .claude/agents/code-reviewer.md) ให้เพิ่มฟิลด์ใน frontmatter:

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

You're a meticulous reviewer. Read the diff and look for logic errors...

ตอนนี้ทุกครั้งที่เปิด subagent นี้ จะได้ worktree ชั่วคราวใน .claude/worktrees/ หาก subagent ไม่ได้เขียนอะไร โฟลเดอร์จะถูกลบโดยอัตโนมัติเมื่อทำงานเสร็จ หากมีการเปลี่ยนแปลงที่ยังไม่ได้ commit Claude จะถามว่าจะเก็บหรือลบ

Branch ฐานของ worktree สำหรับ subagent เหมือนกับของ --worktree: โดยค่าเริ่มต้นคือ origin/HEAD; หากตั้ง worktree.baseRef: head ก็จะใช้ local HEAD

ตารางตัดสินใจ: worktree, /bg, subagent หรือ Agent View#

การใช้งานร่วมกันที่พบบ่อย:

• “2 ฟีเจอร์พร้อมกัน แบบทำเอง” — สองเทอร์มินัล แต่ละอันรัน claude --worktree เป็นกรณีที่ง่ายที่สุด
• “เริ่ม refactor ข้ามคืน เดี๋ยวฉันปิดแอป” — /bg + /goal พร้อมเงื่อนไขการเสร็จสิ้น เซสชันทำงานแยกจากหน้าต่างของคุณ
• “หนึ่ง prompt สืบค้นสามเรื่องพร้อมกัน” — subagent สามตัวที่มี isolation: worktree แต่ละตัวอยู่ใน sandbox ของตัวเอง
• “ตอนนี้กำลังทำอะไรอยู่?” — claude agents แดชบอร์ดของทุกเซสชัน พร้อมตัวกรอง “running”, “blocked” และ “done”

ข้อผิดพลาด 5 อย่างในการทำงานกับ worktree#

1. เปิด worktree แล้ว .env หาย ไม่มีอะไรทำงาน ปัญหาที่พบบ่อยที่สุด Worktree คือ checkout ใหม่ที่ไม่มีไฟล์ซึ่ง Git ไม่ติดตาม วิธีแก้คือเพิ่มไฟล์ .worktreeinclude ที่มี .env* และไฟล์กำหนดค่าในเครื่องที่จำเป็นทันทีเมื่อตั้งค่าโหมด worktree ตรวจสอบว่าไฟล์อยู่ที่ root ของ repository ไม่ใช่ใน .claude/

2. ต้องการสลับไป branch หลัก จึงรัน cd ไปยัง root แล้วสูญเสียการเปลี่ยนแปลงที่ยังไม่ได้ commit ใน worktree โฟลเดอร์ root และ worktree เป็นสำเนาทำงานคนละชุดกัน จริง ๆ คุณกลับมาด้วย cd; การเปลี่ยนแปลงใน worktree ยังคงอยู่ที่เดิม ไม่ได้หายไปไหน แต่หากสับสนแล้วรัน git stash ในโฟลเดอร์หลักโดยคิดว่าตัวเองอยู่ใน worktree, stash จะถูกสร้างบน branch หลัก ไม่ใช่ branch ที่คุณคาดไว้

3. เปิด 5 เซสชันพร้อมกันแล้วจำไม่ได้ว่าแต่ละเซสชันทำอะไร เอกสารของ Anthropic เตือนอย่างชัดเจนว่านักพัฒนาส่วนใหญ่รับมือมากกว่า 2–3 เซสชันในทางความคิดไม่ไหว สัญญาณของภาวะรับมือไม่ไหวคือเปิด Agent View แล้วไม่สามารถบอกได้ทันทีว่า agent แต่ละตัวกำลังทำอะไร จำกัดเซสชันที่ทำงานพร้อมกันไว้สองเซสชัน หากงานต้องใช้มากกว่านั้น ควรประสานงานผ่าน /goal + subagent ไม่ใช่ทำด้วยตนเอง

4. Worktree จาก -p (headless) ไม่ถูกล้างโดยอัตโนมัติ คำสั่ง claude --worktree feature-x -p "do thing" ไม่แสดงข้อความถามก่อนออกแบบโต้ตอบ จึงไม่มีจังหวะที่ Claude ถามว่า “remove the worktree?” Worktree เหล่านี้จึงสะสม ล้างด้วยตนเอง: git worktree remove .claude/worktrees/feature-x หรือใช้สคริปต์ cron ที่ลบรายการที่เก่ากว่า 7 วัน

5. กล่องโต้ตอบความเชื่อถือในโฟลเดอร์ใหม่ หากเปิด repository เป็นครั้งแรกแล้วรัน claude --worktree ทันที คำสั่งจะล้มเหลว รัน claude โดยไม่มีแฟล็ก ยอมรับความเชื่อถือของ workspace แล้วออก จากนั้น --worktree จะทำงาน ซึ่งตั้งใจให้เป็นเช่นนี้ เพื่อไม่ให้ Claude เข้าถึงโปรเจกต์ของคนอื่นโดยไม่ได้รับความยินยอมจากผู้ใช้

การล้างข้อมูล: อะไรถูกลบโดยอัตโนมัติ#

ตรรกะการล้างข้อมูลขึ้นอยู่กับสิ่งที่คุณทำใน worktree และวิธีที่ใช้เริ่มเซสชัน เอกสารของ Anthropic ระบุสามสถานการณ์:

สถานการณ์ 1: คุณเข้าไป ไม่ได้ทำอะไร แล้วออก — worktree ถูกลบ

สถานการณ์ 2: คุณทำงานบางอย่างแต่ไม่ได้ commit — Claude จะถาม “keep or remove?” เมื่อคุณออก “Keep” จะเก็บโฟลเดอร์และ branch ไว้ใช้ภายหลัง “Remove” จะลบไดเรกทอรี พร้อมกับ การเปลี่ยนแปลงที่ยังไม่ได้ commit และ commit ใหม่ การกระทำนี้ทำลายข้อมูล อย่าคลิก “remove” โดยไม่คิด

สถานการณ์ 3: คุณเริ่มด้วย -p (headless) แล้วคำสั่งทำงานเสร็จและออก worktree จะยังคงอยู่ ให้ล้างด้วยตนเอง:

git worktree remove .claude/worktrees/feature-x

นอกจากนี้ worktree จาก subagent และเซสชัน /bg จะถูกลบโดยอัตโนมัติผ่านการล้างข้อมูลเบื้องหลัง หากมีอายุมากกว่า cleanupPeriodDays วัน (การตั้งค่า ซึ่งโดยทั่วไปมีค่าเริ่มต้น 30 วัน) และ ไม่มีงานที่ยังไม่ได้บันทึก การล้างข้อมูลอัตโนมัติจะไม่แตะ worktree จาก --worktree — เป็นความรับผิดชอบของคุณ

ทางเลือกสำหรับ SVN, Perforce และ Mercurial: hook WorktreeCreate#

หาก repository ใช้ Subversion หรือ Mercurial แฟล็ก --worktree จะใช้โดยตรงไม่ได้ Anthropic มีจุดต่อขยายผ่าน hook สองตัว: WorktreeCreate (สร้างสำเนาที่แยกออกมา) และ WorktreeRemove (ลบสำเนานั้น)

ตัวอย่าง hook SVN จากเอกสารทางการ:

{
  "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 อ่านชื่อ worktree จาก stdin ({ "name": "feature-auth" }), รัน svn checkout ไปยังไดเรกทอรีที่กำหนดไว้ล่วงหน้า และพิมพ์ path ออกทาง stdout — Claude Code จะใช้เป็นไดเรกทอรีทำงานของเซสชันใหม่

ข้อควรระวังที่สำคัญ: เมื่อใช้ hook ของคุณเอง จะไม่มีการใช้ .worktreeinclude หากต้องการให้ .env หรือไฟล์อื่นที่ Git ไม่ติดตามอยู่ในโฟลเดอร์ใหม่ ให้คัดลอกไฟล์เหล่านั้นในสคริปต์ hook เอง

ต่อไป: กลไกคู่ขนานที่เกี่ยวข้องอีกสามอย่าง#

Worktree ให้การแยกไฟล์ /bg ให้การแยก context Subagent ให้การแยกงาน กลไกแต่ละอย่างแก้ปัญหาเฉพาะตัว เมื่อใช้ร่วมกันจะทำให้ทำงานสามถึงห้างานพร้อมกันได้โดยไม่เกิดภาวะสมองล้น นี่คือชุดทักษะเบื้องหลัง vibe-coding ขั้นสูงในปี 2026

หัวข้อนี้ต่อยอดไปสู่สามเรื่องที่เกี่ยวข้องโดยตรง: วิธีตั้งค่า agent อัตโนมัติโดยใช้ /goal และ Agent View, วิธีสร้าง subagent ของคุณเองสำหรับงานต่าง ๆ และ วิธีเปิด agent หลายร้อยตัวผ่าน Dynamic Workflows

เปิด Ailoot.