📘 תיעוד 39

הרצת הפעלות מקבילות עם worktrees

בידוד הפעלות מקבילות של Claude Code ב-git worktrees נפרדים כדי ששינויים לא יתנגשו. מכסה את הדגל --worktree, בידוד סוכני משנה, .worktreeinclude, ניקוי, ו-hooks של מערכות בקרת גרסאות שאינן git.

git worktree הוא ספריית עבודה נפרדת עם קבצים וענף משלה, החולקת את אותה היסטוריית מאגר ואותו remote כמו ה-checkout הראשי שלך. הרצת כל הפעלת Claude Code ב-worktree משלה פירושה שעריכות בהפעלה אחת לעולם אינן נוגעות בקבצים בהפעלה אחרת, כך שהפעלה אחת יכולה לבנות תכונה בזמן שהשנייה מתקנת באג.

הערה: worktrees דורשים מאגר git. עבור מערכות בקרת גרסאות אחרות, הגדר hooks שיחליפו את לוגיקת git. ביישום שולחן העבודה, בחר באפשרות worktree בעת הפעלת סשן כדי להקצות לו worktree משלו.

worktrees הם אחת מכמה דרכים להריץ את Claude במקביל. הם מבודדים עריכות קבצים. סוכני משנה מפצלים עבודה בתוך הפעלה אחת, והעברת הודעות בין הפעלות מאפשרת ל-Claude להעביר ממצאים בין ההפעלות שב-worktrees שלך. ראה הרצת סוכנים במקביל כדי להשוות בין הגישות, או דלג קדימה אל בידוד סוכני משנה באמצעות worktrees כדי להשתמש ב-worktrees ובסוכני משנה יחד.

רוב ההפעלות זקוקות רק לשני החלקים הראשונים: הפעלת Claude ב-worktree, ולאחר מכן ניקוי בעת היציאה. חזור לשאר הדף כאשר תצטרך לחדש הפעלה, לשנות את אופן יצירת ה-worktrees, או לנפות שגיאות בכשל.

#הפעלת Claude ב-worktree

העבר את --worktree או את -w עם שם כדי ליצור worktree מבודד ולהפעיל את Claude בתוכו. כברירת מחדל, ה-worktree נוצר תחת .claude/worktrees/<name>/ בשורש המאגר שלך, על גבי ענף חדש בשם worktree-<name>:

claude --worktree feature-auth

הרץ את הפקודה שוב עם שם אחר בטרמינל נוסף כדי להפעיל סשן מבודד שני. אם תשמיט את השם, Claude ייצר שם כמו bright-running-fox.

הרצות אינטראקטיביות דורשות אמון בסביבת העבודה (workspace trust): אם לא הרצת את Claude בספרייה בעבר, הרץ שם את claude פעם אחת כדי לאשר את תיבת הדו שיח של האמון, אחרת --worktree יוצא עם שגיאה המנחה אותך לעשות זאת. הרצות שאינן אינטראקטיביות עם -p מדלגות על בדיקת האמון, כך ש-claude -p --worktree ממשיך בלעדיה.

טיפ: הוסף את .claude/worktrees/ לקובץ ה-.gitignore שלך כדי שתוכן ה-worktree לא יופיע כקבצים שאינם במעקב (untracked files) ב-checkout הראשי שלך.

#הגדרת סביבת ה-worktree

worktree הוא checkout חדש ונקי, לכן אתחל שם את סביבת הפיתוח שלך: בקש מ-Claude להתקין תלויות, או הרץ את הגדרת הפרויקט בעצמך בספריית ה-worktree תחת .claude/worktrees/. כדי להעביר קבצים המוגדרים ב-gitignored, כגון .env, לכל worktree חדש באופן אוטומטי, הוסף קובץ .worktreeinclude.

#בקשה מ-Claude ליצור worktree

תוכל גם לבקש מ-Claude "לעבוד ב-worktree" במהלך סשן, והוא ייצור אחד באמצעות הכלי EnterWorktree. ברגע שנמצאים ב-worktree, Claude יכול לעבור ישירות ל-worktree אחר תחת .claude/worktrees/ על ידי קריאה ל-EnterWorktree עם נתיב היעד. ה-worktree הקודם נשאר בדיסק ללא שינוי.

כאשר Claude נכנס לנתיב מחוץ לספריית .claude/worktrees/ של המאגר, Claude Code מבקש את אישורך תחילה, מכיוון שהמעבר מעביר את ספריית העבודה של הסשן, את הרשאות הכתיבה, ואת תצורת הפרויקט כגון CLAUDE.md והגדרות אל אותו מיקום. כלל הרשאות עבור EnterWorktree או בחירה באפשרות "don't ask again" אינם משתיקים בקשה זו. רק מצב bypassPermissions מדלג עליה. לפני גרסה v2.1.206, Claude יכול היה להיכנס לכל נתיב worktree קיים מבלי לבקש אישור.

הערה: נתיבי hook אינם עוקבים אחרי ה-worktree. לאחר ש-Claude נכנס ל-worktree, Claude Code שומר על ${CLAUDE_PROJECT_DIR} ב-hooks שלך במקומו המקורי ומעביר אליהם את נתיב ה-worktree בדרך אחרת:

• ${CLAUDE_PROJECT_DIR} נשאר במקומו: הוא עדיין מצביע על שורש הפרויקט שבו התחיל הסשן, כך שפקודת hook כמו ${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh עדיין מריצה את הסקריפט ב-checkout הראשי.
• cwd עוקב אחרי Claude: השדה cwd ב-input JSON של ה-hook הוא שורש ה-worktree, והוא זז שוב כאשר Claude מריץ cd. קרא אותו כאשר hook זקוק לנתיב ה-worktree.

#ניקוי worktrees

כאשר אתה יוצא מסשן worktree אינטראקטיבי, Claude בודק ב-worktree האם קיימת עבודה שהסרה תמחק: קבצים שהשתנו או שאינם במעקב, והתחייבויות (commits) חדשות.

• ה-worktree נקי: עבור סשן ללא שם, Claude מסיר את ה-worktree ואת הענף שלו באופן אוטומטי. סשן בעל שם מציג שאלה תחילה כדי שתוכל לשמור את ה-worktree למועד מאוחר יותר.
• יש עבודה בתוך ה-worktree: Claude שואל אותך האם לשמור או להסיר את ה-worktree. שמירה משמרת את הספרייה ואת הענף כדי שתוכל לחזור מאוחר יותר. הסרה מוחקת את ספריית ה-worktree ואת הענף שלו, יחד עם כל העבודה שבתוכם.

להרצות שאינן אינטראקטיביות עם -p אין שאלת יציאה, לכן Claude אינו מנקה את ה-worktrees שלהן, ו-Claude Code משאיר את הנעילה שהוא החיל על כל אחד מהם בעת היצירה במקומה עד אשר סריקת נעילות ישנות (stale-lock sweep) של סשן מאוחר יותר תשחרר אותה. כדי להסיר worktree כזה, הרץ git worktree remove. אם git מסרב מכיוון שה-worktree נעול, הרץ עליו תחילה git worktree unlock.

ב-Windows, הסרת worktree אינה מוחקת קבצים מחוצה לו. אם תיקייה בתוך ה-worktree היא קישור למקום אחר, כגון צומת NTFS (NTFS junction) או symlink של ספרייה, Claude Code מוחק רק את הקישור ושומר על התיקייה שאליה הוא מצביע. לפני גרסה v2.1.205, הסרת worktree עם קישור המקונן בספריית משנה יכלה למחוק את התיקייה שאליה הוא הצביע.

#חידוש סשן worktree

כאשר אתה מחדש סשן שהיה בתוך worktree, Claude Code מחזיר את הסשן לאותו worktree. הדבר נכון עבור חידוש אינטראקטיבי, עבור --continue ו---resume במצב שאינו אינטראקטיבי עם -p, ועבור ה-Agent SDK. בחזרה בתוך ה-worktree, Claude עדיין יכול לצאת ממנו באמצעות הכלי ExitWorktree.

לפני החזרת הסשן ל-worktree שלו, Claude Code מוודא שה-worktree הוא עדיין checkout נפרד מה-checkout הראשי, ומסרב להיכנס מחדש ל-worktree שנכשל בבדיקה. עבור git worktree, הבדיקה קוראת את המטא-דאטה שלו ב-git. worktree ללא מטא-דאטה של git, כגון כזה שנוצר על ידי hook מסוג WorktreeCreate, יכול לעבור את הבדיקה. המקרים שבהם Claude Code עדיין מסרב מפורטים יחד עם דרכי השחזור שלהם תחת Claude Code מסרב להשתמש ב-worktree. להודעות ולאופן השחזור מכל אחת מהן, ראה הסשן מתחדש מחוץ ל-worktree שלו.

המיקום שממנו אתה מפעיל, ואופן החידוש, משנים את מה ש-Claude Code נכנס אליו מחדש:

• ספריית ההפעלה: חידוש מתוך ה-checkout הראשי או מספרייה אחרת של המאגר. Claude Code נכנס מחדש ל-worktree שהוא יצר עם git תחת .claude/worktrees/ גם כאשר אתה מפעיל מתוכו. כאשר אתה מפעיל מתוך כל worktree אחר, Claude Code נכנס אליו מחדש רק אם הוא יכול לערוב לו משם: worktree שהוא מאגר עצמאי, worktree ללא מטא-דאטה של git, או הפעלה מספריית משנה של worktree שיצרת עם git worktree add נדחים, לכן הפעל אותם מה-checkout הראשי.
• --fork-session: הסשן המפוצל מתחיל בספרייה שממנה הפעלת את Claude, ו-Claude Code משאיר את ה-worktree של הסשן המקורי ללא שינוי.
• worktree שנמחק: אם ספריית ה-worktree אינה קיימת עוד, Claude Code מחדש את הסשן בספרייה שממנה הפעלת את Claude. הוא מודיע לך שה-worktree אינו קיים ומנקה את שיוך ה-worktree של הסשן.

הערה: לפני גרסה v2.1.212, חידוש שאינו אינטראקטיבי נשאר בספריית ההתחלה ו-ExitWorktree דיווח שאין סשן worktree פעיל שניתן לצאת ממנו.

כאשר Claude נכנס ל-worktree ש-Claude Code יצר באמצעות git או יוצא ממנו, התמליל עוקב אחריו: Claude Code מתעד את הסשן תחת ספריית העבודה החדשה של הסשן, באותו אופן שבו פועלת הפקודה /cd, כך ש-/desktop ו---resume מוצאים אותו שם. יציאה מחזירה אותו באותו אופן. worktree שנוצר על ידי hook מסוג WorktreeCreate שומר את התמליל שלו בספריית ההפעלה. דורש את Claude Code בגרסה v2.1.198 ומעלה.

#כיצד Claude Code אוכף בידוד

בזמן שסשן מבודד ב-worktree, Claude Code חוסם את קריאות הכלים שהבדיקות להלן מגדירות. אותם כללים חלים בין אם התחלת את הסשן באמצעות --worktree, בין אם Claude נכנס ל-worktree באמצעות EnterWorktree, ובין אם חידשת סשן worktree.

אותה אכיפה חלה על כל סוכן משנה ש-Claude יוצר מהסשן המבודד. היא חלה בין אם הסשן אינטראקטיבי ובין אם הוא רץ ברקע. סוכני משנה שרצים ב-worktree משלהם נושאים את אותן בדיקות. היסטוריית הגרסאות שלהם מופיעה תחת כתיבת קובצי סוכן משנה.

Claude Code מפעיל ארבע בדיקות:

• עריכות קבצים: Claude Code חוסם קריאות Edit, Write, או NotebookEdit שמכוונות לנתיב ב-checkout הראשי.
• ספריית עבודה של פקודה: Claude Code חוסם פקודת Bash, PowerShell, או Monitor שספריית העבודה שלה נפתרת ל-checkout הראשי, או שאינו יכול לוודא שספריית העבודה שלה נשארת מחוצה לו.
• הפניות git: Claude Code חוסם פקודת Bash או Monitor שמפנה את git אל ה-checkout הראשי. ההפניה יכולה להגיע דרך git -C, דרך --git-dir, דרך משתנה GIT_DIR או GIT_WORK_TREE, או דרך cd אל ה-checkout הראשי לפני הרצת git.
• מבנה פקודה: Claude Code חוסם פקודת Bash או Monitor כאשר אינו יכול לוודא מטקסט הפקודה שכל פעולת git שהפקודה מריצה נשארת בתוך ה-worktree, למשל כאשר שם הפקודה מחושב בזמן ריצה או שלא ניתן לפענח את התחביר. Claude Code מסביר ל-Claude כיצד לכתוב מחדש את הפקודה שסורבה, כגון פיצולה לפקודות פשוטות ונפרדות. לא ניתן לכבות בדיקה זו.

הבדיקות חלות על המאגר שממנו הפעלת את Claude Code. הן חלות גם על ה-checkout הראשי שממנו מקושר worktree מקושר. עבור פקודות PowerShell, Claude Code מפעיל רק את בדיקת ספריית העבודה.

Claude רואה כל סירוב כשגיאת כלי שמציינת את ה-worktree ומסבירה כיצד להמשיך.

#בידוד סוכני משנה באמצעות worktrees

סוכני משנה יכולים לרוץ ב-worktrees משלהם כדי שעריכות מקבילות לא יתנגשו. בקש מ-Claude: "use worktrees for your agents", או הפוך את הבידוד לקבוע עבור סוכן משנה מותאם אישית על ידי הוספת isolation: worktree ל-frontmatter שלו.

סוכן משנה זה ב-.claude/agents/ רץ תמיד ב-worktree משלו:

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---

Apply the requested refactor across every affected file, then run the tests
and report the results.

כל סוכן משנה מקבל worktree זמני ש-Claude Code מסיר אוטומטית כאשר סוכן המשנה מסיים ללא שינויים. worktree עם שינויים נשאר בדיסק עד שהסריקה התקופתית להלן תוכל להסיר אותו מבלי לאבד עבודה.

worktrees של סוכני משנה משתמשים באותו ענף בסיס כמו --worktree, ולכן הם מתפצלים מענף ברירת המחדל של המאגר שלך אלא אם כן worktree.baseRef מוגדר כ-"head".

#ניקוי worktrees של סוכני משנה ושל הפעלות ברקע

Claude Code מריץ סריקה תקופתית המסירה worktrees ש-Claude יצר עבור סוכני משנה ועבור הפעלות ברקע ברגע שהם ישנים יותר מהגדרת cleanupPeriodDays שלך, בהתאם לכללי סריקת השימור.

כאשר אתה מעביר לרקע סשן --worktree, ה-worktree שלו הופך ל-worktree של סשן רקע שהסריקה יכולה להסיר. הסריקה משאירה worktree במקומו במקרים הבאים:

• ה-worktree עדיין מכיל עבודה: קבצים שהשתנו או שאינם במעקב, או התחייבויות שלא נדחפו.
• Claude Code אינו יכול לקבוע אילו מנהלי סינון מוגדרים בתצורת המאגר, בכל אחד משלושת המקרים שחוסמים גם יצירת worktree.
• ה-worktree שייך לסשן --worktree שלא העברת לרקע, ללא קשר לגילו.
• יצרת את ה-worktree בעצמך באמצעות git worktree add, גם אם לאחר מכן הרצת בו סשן --worktree <name> והעברת את אותו סשן לרקע.

Claude Code כותב סימון במטא-דאטה של git בכל worktree שהוא יוצר עם git, והסריקה שומרת כל worktree ללא סימון זה, כולל worktree שנוצר על ידי hook מסוג WorktreeCreate. לפני גרסה v2.1.246, הסריקה לא בדקה את הסימון, ויכלה להסיר worktree שיצרת בעצמך כאשר רשומת סשן רקע ישנה הצביעה עליו.

בזמן שסוכן פועל, Claude Code מחזיק git worktree lock על ה-worktree שלו כדי שניקוי מקביל לא יוכל להסיר אותו, ומשחרר את הנעילה כאשר הסוכן מסיים. Claude Code מחזיק את אותה נעילה על ה-worktree שהוא יצר עבור סשן שהועבר לרקע כל עוד הסשן פועל, כך שהסריקה משאירה את ה-worktree במקומו ו-git worktree remove מסרב להסירו.

הסריקה משחררת גם נעילה ש-Claude Code הגדיר עבור סשן שתהליך הריצה שלו הסתיים, כך שסשן רקע שחוסל אינו משאיר את ה-worktree שלו נעול לצמיתות. הסריקה לעולם אינה משחררת נעילה שהגדרת בעצמך באמצעות git worktree lock. לפני גרסה v2.1.210, נעילה שהושארה על ידי סשן שחוסל נשארה במקומה עד שהרצת git worktree unlock.

כדי לנקות worktree שהסריקה שומרת, הרץ git worktree remove, והוסף את --force אם ב-worktree יש שינויים שלא בוצעה עבורם התחייבות או קבצים שאינם במעקב. אם git מסרב מכיוון שה-worktree נעול, הרץ עליו תחילה git worktree unlock.

#התאמה אישית של יצירת worktrees

ברירות המחדל של Claude Code ליצירת worktrees מתאימות לרוב ההפעלות: הוא יוצר אותם תחת .claude/worktrees/, מפצל אותם מענף ברירת המחדל של המאגר שלך, ומבצע checkout לקבצים במעקב בלבד. האפשרויות בסעיף זה משנות ברירות מחדל אלה.

#בחירת ענף הבסיס

worktrees חדשים מתפצלים מענף ברירת המחדל של המאגר, ולכן רוב ההפעלות אינן זקוקות להגדרה זו. הגדר את worktree.baseRef בהגדרות כדי להתפצל מהעבודה הנוכחית שלך במקום זאת. ההגדרה מקבלת שני ערכים:

• "fresh" (ברירת מחדל): התפצלות מענף ברירת המחדל של המאגר ב-remote, בדרך כלל main, כך שה-worktree מתחיל מעץ נקי התואם ל-remote.
• "head": התפצלות מה-HEAD המקומי הנוכחי שלך, כך שה-worktree נושא את ההתחייבויות שטרם נדחפו ואת מצב ענף התכונה (feature-branch). השתמש באפשרות זו בעת בידוד סוכני משנה שצריכים לפעול על עבודה הנמצאת בעיצומה. בתוך worktree, הערך "head" נפתר ל-HEAD של אותו worktree, ולא לזה של ה-checkout הראשי.

לא ניתן להגדיר את worktree.baseRef לשם של ענף. כדי להתחיל worktree מענף קיים מסוים, צור אותו ישירות באמצעות git.

עבור בסיס "fresh", Claude Code שומר על origin/HEAD עדכני: כאשר לא בוצע fetch למאגר ב-24 השעות האחרונות, הוא מבצע fetch לענף ברירת המחדל, עם מגבלת זמן של חמש שניות, ומשתמש ב-ref השמור במטמון המקומי אם ה-fetch נכשל. אם לא הוגדר remote, או ש-origin/HEAD אינו שמור במטמון מקומית ואינו ניתן למשיכה, ה-worktree נסוג ל-HEAD המקומי הנוכחי שלך. לפני גרסה v2.1.208, worktree מסוג fresh השתמש במה שכבר היה שמור במטמון המקומי כ-origin/HEAD.

דוגמה זו גורמת לכל worktree חדש להתפצל מהעבודה הנוכחית שלך:

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

#התפצלות מתוך pull request

כדי להתפצל מתוך pull request או merge request מסוים, העבר ל---worktree את המספר עם הקידומת #, כתובת URL של pull request ב-GitHub, או כתובת URL של merge request ב-GitLab כגון https://gitlab.com/group/repo/-/merge_requests/123. Claude Code מושך את ה-head commit של אותו שינוי מ-origin ויוצר את ה-worktree ב-.claude/worktrees/pr-<number>. הקף את הארגומנט במרכאות כדי שהמעטפת שלך לא תתייחס ל-# כתחילתה של הערה:

claude --worktree "#1234"

Claude Code קורא רק את המספר מתוך כתובת ה-URL. הוא תמיד מושך מ-remote בשם origin של המאגר שלך, ובוחר את נתיב המשיכה לפי המארח (host) של origin:

• github.com: מושך את pull/<number>/head
• gitlab.com: מושך את merge-requests/<number>/head
• GitHub Enterprise, self-managed GitLab, או כל מארח אחר: מנסה תחילה את pull/<number>/head, ולאחר מכן את merge-requests/<number>/head

לפני גרסה v2.1.233, Claude Code קיבל רק #<number> וכתובות URL של pull request בסגנון GitHub עבור --worktree, ותמיד משך את pull/<number>/head.

#העתקת קבצים שב-gitignored אל תוך worktrees

worktree הוא checkout חדש ונקי, כך שקבצים שאינם במעקב כגון .env או .env.local מהמאגר הראשי שלך אינם קיימים בו. כדי להעתיק אותם באופן אוטומטי כאשר Claude יוצר worktree, הוסף קובץ .worktreeinclude לשורש הפרויקט שלך.

הקובץ משתמש בתחביר של .gitignore. מועתקים רק קבצים שתואמים לתבנית ומופיעים גם ב-gitignored, כך שקבצים במעקב לעולם אינם משוכפלים.

אם אתה כותב תבנית שמתחילה ב-**/ והקבצים שאתה רוצה נמצאים בתוך ספרייה שמוגדרת כולה ב-gitignored, Claude Code מעתיק אותם רק כאשר הספרייה עצמה תואמת לתבנית, או כאשר השם הראשון לאחר **/ הוא אחד השמות בנתיב הספרייה. לדוגמה, אם אתה כותב **/.claude/skills/*.md, השם הראשון הוא .claude, ולכן Claude Code מעתיק את הקבצים התואמים מתוך ספריית .claude/ שמוגדרת ב-ignored. כדי להעתיק קבצים מתוך ספרייה מוגדרת כ-ignored שתבנית **/ אינה מגיעה אליה, ציין את שם הספרייה בתבנית במקום זאת: כתוב vendor/**/config.json ולא **/config.json. לפני גרסה v2.1.239, Claude Code העתיק קבצים מתוך ספרייה שהתעלמו ממנה לחלוטין עבור תבנית **/ רק כאשר הספרייה עצמה התאימה לתבנית.

קובץ .worktreeinclude זה מעתיק שני קובצי env והגדרות סודות (secrets) לכל worktree חדש:

.env
.env.local
config/secrets.json

הדבר חל על כל worktree ש-Claude Code יוצר באמצעות git: על worktrees של --worktree, על worktrees של סוכני משנה, ועל הפעלות מקבילות ביישום שולחן העבודה. עם hook מסוג WorktreeCreate, העתק את הקבצים בתוך סקריפט ה-hook.

#שימוש חוזר בשם של worktree

העברת שם ל---worktree שהספרייה שלו כבר קיימת פותחת את ה-worktree הקיים במקום ליצור אחד חדש.

עם בסיס "fresh" שמוגדר כברירת מחדל, worktree שנפתח מחדש מתאפס לענף ברירת המחדל של המאגר במקום להמשיך בקצה (tip) הישן שלו כאשר כל התנאים הבאים מתקיימים:

• אין בו שינויים שלא בוצעה עבורם התחייבות או קבצים שאינם במעקב.
• הוא עדיין נמצא על הענף ש-Claude Code יצר עבורו.
• אין לו התחייבויות משלו, או שה-pull request או ה-merge request שלו מוזגו והענף המרוחק שלו נמחק.

Claude Code מזהה את מקרה המיזוג ממצב ה-git בלבד: הענף המרוחק שה-worktree דחף אליו אינו קיים עוד, וכל התחייבות ב-worktree כבר נמצאת בענף ברירת המחדל.

בכל מקרה אחר, Claude Code פותח מחדש את ה-worktree בקצה הישן שלו:

• ה-worktree אינו עומד באחד התנאים.
• ל-Claude Code אין אפשרות לאמת את מצב ה-worktree.
• worktree.baseRef מוגדר כ-"head".
• השם הוא הפניה ל-pull request או ל-merge request.

לפני גרסה v2.1.208, כאשר השתמשת מחדש בשם, Claude Code תמיד פתח מחדש את ה-worktree הישן בקצה הישן שלו.

#החלפת יצירת worktree באמצעות hook

הגדר hook מסוג WorktreeCreate כדי להחליף לחלוטין את לוגיקת git worktree המוגדרת כברירת מחדל, כולל מיקום worktrees במקום אחר שאינו .claude/worktrees/. לדוגמה מלאה, ראה בקרת גרסאות שאינה git.

#מה ש-worktrees חולקים עם ה-checkout הראשי

worktree מקבל קבצים וענף משלו, אך הוא חולק עם ה-checkout הראשי את ספריית ה-.git של המאגר, תוספים ברמת הפרויקט (project-scope plugins), ואישורי הרשאות שמורים:

• ספריית ה-.git של המאגר: פקודות git ב-worktree כותבות לספריית ה-.git המשותפת של המאגר הראשי, וארגז החול (sandboxing) מאפשר כתיבות אלה, כך שפקודות כגון git commit פועלות מתוך worktree כאשר ארגז החול מופעל.
• תוספים: תוספים שהותקנו בהיקף הפרויקט (project scope) מה-checkout הראשי נטענים גם ב-worktrees של אותו מאגר, כך שאין צורך להתקין אותם מחדש עבור כל worktree. דורש את Claude Code בגרסה v2.1.200 ומעלה.
• אישורי הרשאות: בחירה ב-"Yes, and don't ask again" עבור פקודת Bash בסשן worktree שומרת את הכלל בקובץ .claude/settings.local.json של ה-checkout הראשי, כך שהוא חל ב-checkout הראשי ובכל worktree אחר של המאגר, והוא שורד את הסרת ה-worktree. ב-Windows ובמקרים האחרים שבהם Claude Code אינו משתמש בשורש המאגר, הכלל נשאר עם אותו worktree. לפני גרסה v2.1.211, אישור שניתן ב-worktree נשמר בתוך אותו worktree, לא חל במקומות אחרים, ואבד בעת הסרת ה-worktree. ראה היכן נשמרים אישורים.

שלושתם חלים בין אם יצרת את ה-worktree עם --worktree, עם git worktree add, או דרך יישום שולחן העבודה.

#ניהול worktrees באופן ידני

צור worktrees ישירות עם Git כאשר אתה צריך לבצע checkout לענף קיים מסוים או למקם את ה-worktree מחוץ למאגר.

יצירת worktree בענף חדש:

git worktree add ../project-feature-a -b feature-a

יצירת worktree מענף קיים, תוך החלפת fix-issue-456 בענף שכבר קיים במאגר שלך:

git worktree add ../project-bugfix fix-issue-456

הפעלת Claude בתוך ה-worktree:

cd ../project-feature-a
claude

הצגת רשימת ה-worktrees שלך:

git worktree list

הסרת worktree בסיום השימוש בו:

git worktree remove ../project-feature-a

לעיון במדריך הפקודות המלא, ראה את תיעוד Git worktree.

#בקרת גרסאות שאינה git

בידוד worktree משתמש ב-git כברירת מחדל. עבור SVN, Perforce, Mercurial, או מערכות אחרות, הגדר hooks מסוג WorktreeCreate ו-WorktreeRemove כדי לספק לוגיקת יצירה וניקוי מותאמת אישית. מכיוון שה-hook מחליף את התנהגות git המוגדרת כברירת מחדל, הקובץ .worktreeinclude אינו מעובד בעת שימוש ב---worktree. העתק קובצי תצורה מקומיים בתוך סקריפט ה-hook שלך במקום זאת.

hook זה מסוג WorktreeCreate קורא את שם ה-worktree מתוך ה-JSON ב-stdin באמצעות jq, מבצע checkout לעותק עבודה (working copy) חדש של SVN, ומדפיס את נתיב הספרייה כדי ש-Claude Code יוכל להשתמש בו כספריית העבודה של הסשן. הוסף את התצורה אל settings.json שלך:

{
  "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 מסוג WorktreeRemove כדי לבצע ניקוי בסיום הסשן. ראה את מדריך ה-hooks עבור סכמת הקלט ודוגמה להסרה.

#פתרון בעיות

Claude Code מדווח על השגיאות להלן כאשר הוא יוצר worktree, נכנס לאחד עם ההפעלה, או מחזיר סשן שחודש אל worktree.

#Claude Code אינו יכול להיכנס ל-worktree בעת ההפעלה

כאשר Claude Code אינו יכול להיכנס לספריית ה-worktree בעת ההפעלה, הוא מדפיס הודעת שגיאה המציינת את הנתיב ויוצא עם קוד 1. הדבר יכול להתרחש כאשר hook מסוג WorktreeCreate מדפיס משהו שאינו הספרייה שהוא יצר, או כאשר הספרייה נמחקה לאחר הגדרתה.

#יצירת worktree נכשלת בנתיב עם symlink

Claude Code מסרב ליצור worktree כאשר .claude, .claude/worktrees, או ספריית ה-worktree עצמה הם symlink, והשגיאה מציינת את הנתיב שמכיל את ה-symlink. הסר את ה-symlink ונסה שוב. לפני גרסה v2.1.212, אם המאגר כבר הכיל symlink שמור באחד מנתיבים אלה, יצירת ה-worktree עקבה אחריו ויכלה ליצור קבצים מחוץ למאגר.

#קובצי Git LFS הם קובצי מצביע ב-worktree ש-Claude Code יצר

אם הגדרת את Git LFS באמצעות git lfs install --local, worktree ש-Claude Code יוצר יכיל קובצי מצביע (pointer files) של LFS במקום הקבצים האמיתיים. הדגל --local כותב את מסנן ה-LFS לתוך קובץ .git/config של המאגר עצמו ולא לתצורת ה-git הגלובלית שלך. הרצה רגילה של git lfs install כותבת לתצורה הגלובלית שלך ואינה מושפעת. אותו הדבר חל על כל filter driver אחר המוגדר בתצורה של המאגר עצמו.

Claude Code מדלג על מנהלי הסינון של המאגר עצמו כאשר הוא יוצר worktree, מכיוון ש-filter driver הוא פקודת מעטפת (shell command), וכל גורם שיכול לכתוב למאגר, כולל Claude, יכול היה לשים שם פקודה כזו. לפני גרסה v2.1.247, Claude Code הריץ מנהלי סינון אלה במהלך יצירת worktree.

כדי לקבל את הקבצים האמיתיים, הרץ git lfs pull בתוך ה-worktree.

בשלושה מקרים נדירים, Claude Code אינו יכול לדעת אילו מנהלי סינון מוגדרים בתצורת המאגר, ואינו יוצר worktree כלל. התאם את השגיאה לפתרון שלה:

• Could not read the repository git config to neutralize filter drivers: ל-Claude Code לא הייתה אפשרות לקרוא את קובץ .git/config של המאגר, למשל בגלל הרשאות הקובץ. תקן זאת ונסה שוב.
• The repository git config defines a filter driver whose name cannot be neutralized (contains "=" or a newline): שנה את שמו של אותו filter driver ב-.git/config או הסר אותו, ונסה שוב.
• The repository git config has a conditional include (includeIf): העבר את ההגדרות שה-includeIf ב-.git/config מייבא ישירות אל תוך אותו קובץ, הסר את ה-includeIf, ונסה שוב. הגדרת includeIf בתצורת ה-git הגלובלית שלך אינה מפעילה זאת.

#Claude Code מסרב להשתמש ב-worktree

שגיאה שמתחילה ב-Refusing to use <path> as an isolation worktree פירושה ש-Claude Code בדק את זהות ה-git של הספרייה לפני אימוצה כ-checkout מבודד של סשן או של סוכן משנה, ודחה אותה. הבדיקה רצה בין אם Claude Code יוצר את ה-worktree, נכנס ל-worktree קיים, או עושה שימוש חוזר ב-worktree מהרצה קודמת.

ברוב המקרים שאר ההודעה אומר שהמטא-דאטה של ה-git בספרייה נפתר אל ה-checkout הראשי: לדוגמה, קובץ ה-.git שלה מצביע על ספריית ה-.git של המאגר הראשי עצמו, או ש-git פותר את עץ העבודה (working tree) שלו אל ה-checkout הראשי דרך הפניית core.worktree. מספרייה כזו, פקודת git רגילה כגון git reset --hard תפעל על ה-checkout הראשי במקום על ה-worktree. Claude Code מסרב גם כאשר בספרייה יש רשומת .git שאינו יכול לקרוא, במקום להניח שה-worktree בטוח.

ספרייה ללא מטא-דאטה של git כלל, כגון ספרייה ש-hook מסוג WorktreeCreate שלך יוצר, עוברת את הבדיקה רק כאשר אף מאגר git אינו מכיל אותה. אם ה-hook יוצר את הספרייה בתוך מאגר, git פותר אותה אל ה-checkout של אותו מאגר ו-Claude Code מסרב לה עם ההודעה git resolves its working tree to, לכן דאג שה-hook ייצור את הספריות שלו מחוץ לכל מאגר.

Claude Code משאיר את הספרייה שסורבה במקומה, מכיוון שהיא עשויה להכיל עבודה. התאם את ההודעה לדרך השחזור שלה, בין אם היא מופיעה אחרי Refusing to use <path> ובין אם היא מופיעה בהודעת חידוש. חלק מהסיומות מופיעות רק בהודעות חידוש:

• נאמר launch from the parent checkout או Run the resume from the project checkout: הפעלת את Claude Code מתוך ה-worktree. הפעל מה-checkout הראשי במקום זאת. ה-worktree אינו דורש יצירה מחדש.
• נאמר it cannot be resumed or re-entered: שום דבר בסשן זה אינו ערב ל-worktree מהמיקום שממנו הפעלת. צור אותו מחדש. הספרייה והעבודה שבה נשארות בדיסק לשחזור ידני, וכאשר ל-worktree יש checkout אב, חידוש משם עובד גם כן.
• נאמר it contains the protected checkout: הספרייה שסורבה היא ספריית אב של ה-checkout הראשי שלך, כגון ספריית הבית שלך. אל תמחק אותה. שנה את נתיב ה-worktree, כגון הנתיב ש-hook של WorktreeCreate מחזיר או היעד של EnterWorktree, כך שה-worktree לא יכיל את ה-checkout.
• נאמר the protected checkout <path> has a .git entry that could not be examined או has git metadata that could not be resolved: הבעיה היא במטא-דאטה של ה-git ב-checkout הראשי, ולא בזו של ה-worktree. אל תמחק את ה-worktree, והתעלם מההמלצה בסוף ההודעה ליצור אותו מחדש, שאינה חלה על שתי סיומות אלו. תקן את ה-checkout הראשי, למשל בעיית הרשאות או סירוב מסוג dubious ownership של git על ה-.git שלו, ונסה שוב.
• נאמר its recorded path has a network spelling: Claude Code לעולם אינו מחדש סשן לתוך worktree בנתיב רשת. צור מחדש את ה-worktree בנתיב מקומי.
• כל סיומת אחרת: ההודעה מציינת את הבעיה ואת הפתרון שלה, כגון הסרת הפניית core.worktree או יצירת ה-worktree מחדש. פעל לפיה. לפני מחיקת ספרייה שההודעה לגביה מציינת שלא ניתן היה לאמת את זהות ה-git שלה, טפל תחילה בגורם המצוין, לדוגמה קישור סמלי (symbolic link) בנתיב של ה-worktree או כישלון בהרצת git עצמו, מכיוון שהספרייה עשויה להיות תקינה. כאשר אתה יוצר מחדש, הצל תחילה שינויים נדרשים מהספרייה הישנה. היא נשארת בדיסק.

#הסשן מתחדש מחוץ ל-worktree שלו

כאשר אתה מחדש סשן באופן אינטראקטיבי ו-Claude Code אינו יכול להחזיר אותו ל-worktree שלו, Claude Code מודיע על כך באמצעות אחת ההודעות להלן. כאשר Claude Code מנקה את שיוך ה-worktree, הוא מתעד את הניקוי בתמליל הסשן. אם אתה מונע כתיבת תמליל, ההודעה אומרת במקום זאת שלא ניתן היה לנקות את השיוך וכי Claude Code יבדוק מחדש את ה-worktree בחידוש מאוחר יותר.

במצב שאינו אינטראקטיבי עם -p, ובחידושים ש-Agent SDK מריץ, Claude Code עוצר את החידוש עם שגיאת stderr עבור כל סירוב פרט ל-worktree שנמחק, במקום להמשיך ללא בידוד.

עם --output-format stream-json, הסירוב מגיע גם ב-stdout כהודעת result עם תת-סוג error_during_execution שמערך ה-errors שלה נושא את אותו טקסט, כך שיישום Agent SDK מקבל את הסיבה ולא רק יציאה עם קוד שאינו אפס. לפני גרסה v2.1.260, סירוב בחידוש worktree לא הפיק הודעת result.

ההודעות מקבלות צורות שונות מההודעות האינטראקטיביות שבטבלה:

• Error: cannot resume into worktree <path>: ...This session was not started. עבור סירוב שהטבלה מציגה כ-Did not re-enter. Claude Code מנקה את שיוך ה-worktree לפני היציאה, והשגיאה מציינת זאת. בפעם הבאה שתחדש את השיחה, הסשן ימשיך בספרייה הנוכחית ללא בידוד worktree. לפני גרסה v2.1.260, Claude Code לא כתב את השיוך שנוקה, ולכן כל ניסיון חוזר של אותו חידוש נכשל עם אותה שגיאה.

  אם אתה מונע כתיבת תמליל, לא ניתן לשמור את הניקוי. השגיאה אומרת אז שאותה פקודה תסורב שוב, ומציינת את --fork-session ואת התחלת שיחה חדשה כדרכים להמשיך ללא ה-worktree.

• Error: could not verify worktree <path> for this resume, so the resume was aborted... עבור Could not verify

• Error: ...The worktree binding is kept. עבור Could not re-enter

• Notice: the worktree <path> for this session no longer exists... עבור worktree שנמחק. Claude Code מדפיס זאת וממשיך את הסשן, כפי שעושה חידוש אינטראקטיבי

סיומת הסירוב המוטמעת בכל שגיאה משותפת עם ההודעות האינטראקטיביות, ולכן היא עדיין תואמת לרשומה שלה תחת Claude Code מסרב להשתמש ב-worktree.

#ראה גם

worktrees מטפלים בבידוד קבצים. הדפים הקשורים להלן מכסים האצלת עבודה אל תוך checkouts מבודדים אלה, העברת ממצאים ביניהם, ומעבר בין ההפעלות שאתה יוצר:

• סוכני משנה: האצלת עבודה לסוכנים מבודדים בתוך סשן
• העברת הודעות בין הפעלות: מתן אפשרות להפעלות ב-worktrees שלך להעביר ממצאים זו לזו
• צוותי סוכנים: תיאום אוטומטי של מספר הפעלות Claude
• ניהול הפעלות: מתן שמות, חידוש, ומעבר בין שיחות
• הפעלות מקבילות בשולחן העבודה: הפעלות המגובות ב-worktree ביישום שולחן העבודה