📘 תיעוד 46

הרצת סשנים מקבילים עם worktrees

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

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

הערה

אם אתה משתמש במערכת בקרת גרסאות אחרת או באפליקציית הדסקטופ, פעל לפי ההוראות של ההגדרה שלך:

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

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

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

#התחלת Claude ב-worktree

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

claude --worktree feature-auth

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

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

טיפ

הוסף את .claude/worktrees/ ל-.gitignore שלך כדי שתוכן ה-worktree לא יופיע כקבצים לא במעקב ב-checkout הראשי.

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

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

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

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

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

הערה

נתיבי 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 ב-JSON הקלט של ה-hook הוא שורש ה-worktree, והוא זז שוב כש-Claude מריץ cd. קרא אותו כש-hook צריך את נתיב ה-worktree.

#ל-Claude אין כלי EnterWorktree

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

אפשר להמשיך לעבוד ב-worktrees בזמן שהמפתח מופעל:

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

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

#ניקוי worktrees

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

• ה-worktree נקי: עבור סשן ללא שם, Claude מסיר את ה-worktree ואת הענף שלו אוטומטית. סשן עם שם מבקש ממך קודם אישור כדי שתוכל לשמור את ה-worktree להמשך
• יש עבודה ב-worktree: Claude מבקש ממך לשמור או להסיר את ה-worktree. שמירה משמרת את התיקייה ואת הענף. כדי לחזור מאוחר יותר, הרץ את הפקודה claude --worktree <name> --resume ש-Claude Code מדפיס ביציאה. הסרה מוחקת את תיקיית ה-worktree ואת הענף שלו, יחד עם כל העבודה שבהם
• ענף אחר נמצא ב-checkout: אם ה-worktree נמצא על ענף שאינו הענף שלו, ויש לענף הזה commits מעבר ל-commit ההתחלתי של ה-worktree, Claude מבקש ממך לשמור או להסיר את ה-worktree. כל אחת מהתשובות שומרת את הענף האחר ואת ה-commits שלו. הסרה מוחקת את תיקיית ה-worktree ואת הענף של ה-worktree עצמו, זה ש-Claude יצר איתו
• אי אפשר לאמת את מצב ה-worktree: כש-Claude Code לא יכול לספור את השינויים ב-worktree או לא יכול לבדוק את ה-checkout של ה-submodules שלו, הוא מבקש ממך במקום להסיר את ה-worktree אוטומטית. הבקשה מציינת מה הוא לא הצליח לבדוק

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

ב-Windows, הסרת worktree לא מוחקת קבצים שמחוץ לו. אם תיקייה בתוך ה-worktree היא קישור למקום אחר, כגון NTFS junction או symlink של תיקייה, Claude Code מוחק רק את הקישור.

#חידוש סשן worktree

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

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

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

• תיקיית ההפעלה: חדש עם --resume מה-checkout הראשי או מתיקייה אחרת של המאגר. Claude Code נכנס מחדש ל-worktree שהוא יצר עם git תחת .claude/worktrees/ גם כשאתה מפעיל מתוכו. כשאתה מפעיל מתוך כל worktree אחר, Claude Code נכנס אליו מחדש רק אם הוא יכול לאמת אותו משם: 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 אוכף בידוד

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

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

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

• עריכות קבצים: Claude Code חוסם Edit, Write, או NotebookEdit שמכוון לנתיב ב-checkout הראשי. כדי לשנות קובץ ב-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. זה קורה, למשל, כששם הפקודה מחושב בזמן ריצה, כשאי אפשר לנתח את התחביר, או כשהרחבה כגון ${!name} או ${ command; } יכולה להריץ פקודה שהטקסט לא מפרט. Claude Code אומר ל-Claude איך לכתוב מחדש את הפקודה שנדחתה, למשל לפצל אותה לפקודות פשוטות ונפרדות. אי אפשר לכבות את הבדיקה הזו.

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

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

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

#בידוד סוכני משנה עם worktrees

סוכני משנה יכולים לרוץ ב-worktree משלהם כדי שעריכות מקבילות לא יתנגשו. בקשו מ-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 עם שינויים נשאר על הדיסק עד שהסריקה התקופתית למטה יכולה להסיר אותו בלי לאבד עבודה. עבור worktree שה-hook ‏WorktreeCreate שלכם יצר, ראו WorktreeRemove במקום.

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

סוכן משנה ב-worktree משלו לוקח את קבצי ההוראות שהוא מתחיל איתם מהשיחה הראשית שלכם, לא מה-worktree שלו. כאשר ה-worktree הזה נמצא במיקום ברירת המחדל תחת .claude/worktrees/, סוכן המשנה גם לא טוען את הקובץ CLAUDE.md או את הספרייה .claude/rules/ בשורש ה-worktree בזמן שהוא קורא קבצים שם, גם אם אלה שונים בענף של ה-worktree.

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

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

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

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

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

#נעילות worktree והסרה ידנית

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

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

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

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

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

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

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

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

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

עבור בסיס "fresh", Claude Code שומר את origin/HEAD מעודכן:

• כאשר המאגר לא עבר fetch ב-24 השעות האחרונות, הוא מבצע fetch לענף ברירת המחדל, עם תקרה של חמש שניות, ומשתמש ב-ref שנשמר במטמון המקומי אם ה-fetch נכשל.
• ה-fetch אף פעם לא ממתין לקלט בטרמינל שלכם. הוא גם נחשב לכישלון כאשר git או ssh היו מבקשים סיסמה, passphrase של מפתח, או אישור של מארח SSH חדש.
• אם לא מוגדר remote, או ש-origin/HEAD לא שמור במטמון המקומי ואי אפשר לבצע לו fetch, ה-worktree נופל חזרה ל-HEAD המקומי הנוכחי שלכם.

הדוגמה הזו גורמת לכל worktree חדש להסתעף מהעבודה הנוכחית שלכם:

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

#הסתעפות מבקשת משיכה

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

claude --worktree "#1234"

Claude Code קורא רק את המספר מכתובת ה-URL. הוא תמיד מבצע fetch מה-remote ‏origin של המאגר שלכם, ובוחר את נתיב ה-fetch לפי המארח של origin:

• github.com: מבצע fetch ל-pull/<number>/head
• gitlab.com: מבצע fetch ל-merge-requests/<number>/head
• GitHub Enterprise, GitLab בניהול עצמי, או כל מארח אחר: מנסה קודם pull/<number>/head, ואחר כך merge-requests/<number>/head

ה-fetch הזה אף פעם לא ממתין לקלט בטרמינל שלכם. אם git או ssh היו מבקשים סיסמה, passphrase של מפתח, או אישור של מארח SSH חדש, ה-fetch נכשל במקום ו-Claude Code יוצא עם הודעה Error creating worktree: Failed to fetch PR/MR #<number>. מפתח ש-ssh-agent מחזיק עדיין עובד, אז טענו שם את המפתח והריצו git fetch פעם אחת ידנית כדי לרשום מארח חדש לפני שמתחילים.

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

#העתקת קבצים ש-git מתעלם מהם אל worktrees

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

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

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

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

.env
.env.local
config/secrets.json

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

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

אם worktree עם השם שאתם מעבירים ל---worktree כבר קיים, Claude Code פותח אותו במקום ליצור אחד חדש. אם Claude Code נעצר עם שגיאה שמכילה belongs to a different repository או is a leftover worktree, ראו ספריית ה-worktree belongs to a different repository.

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

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

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

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

• ה-worktree נכשל באחד מהתנאים.
• Claude Code לא יכול לאמת את מצב ה-worktree.
• worktree.baseRef הוא "head".
• השם הוא הפניה לבקשת משיכה או לבקשת מיזוג.

#החלפת יצירת worktree ב-hook

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

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

worktree מקבל קבצים וענף משלו, אבל הוא חולק את הדברים הבאים עם ה-checkout הראשי:

• ספריית .git של המאגר: פקודות git ב-worktree כותבות לספריית .git המשותפת של המאגר הראשי, וארגז החול מתיר את הכתיבות האלה, ולכן פקודות כגון git commit עובדות מתוך worktree כשארגז החול מופעל.

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

• אישורי הרשאות: בחירה ב-"Yes, and don't ask again" עבור פקודת Bash בסשן worktree שומרת את הכלל ב-.claude/settings.local.json של ה-checkout הראשי. הכלל חל ב-checkout הראשי ובכל worktree אחר של המאגר, והוא נשאר גם אחרי הסרת ה-worktree.

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

• skills, סוכנים ופקודות לא במעקב: כאשר ל-checkout של ה-worktree אין ספריית .claude/skills בשורש שלו, למשל כי .claude/skills שלכם נמצא ב-gitignore, Claude Code טוען בסשן ה-worktree את ה-skills של הפרויקט מה-checkout הראשי. ב-worktree עם ספריית .claude/skills משלו, רק העותק הזה נטען.

  אותה קריאה דרך מכסה גם את .claude/agents ואת .claude/commands. עבור skills, הקריאה דרך דורשת Claude Code בגרסה v2.1.277 או חדשה יותר.

כל אלה חלים בין אם יצרתם את ה-worktree עם --worktree ובין אם עם git worktree add.

בסשן worktree שמתחילים מאפליקציית שולחן העבודה, Claude Code קורא הגדרות פרויקט כגון settings, hooks, skills, סוכנים, פקודות, ושרתי .mcp.json משורש ה-checkout הראשי. פקודות hook רצות באותו שורש, ו-${CLAUDE_PROJECT_DIR} מצביע אליו. כדי להגיע לקבצים ש-Claude עובד עליהם, קראו את הנתיב של ה-worktree משדה הקלט cwd של ה-hook. קבצי CLAUDE.md ו-.claude/rules/ עדיין נטענים מה-worktree.

#ניהול 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

הסירו אחד כשמסיימים איתו:

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 חדש של עותק עבודה ב-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 עבור סכמת הקלט ודוגמה להסרה.

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

#פתרון בעיות

Claude Code מדווח על השגיאות שלהלן כשהוא יוצר 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 שנשמר ב-commit באחד מהנתיבים האלה, יצירת ה-worktree עקבה אחריו ויכלה ליצור קבצים מחוץ למאגר.

#ל-worktree ש-Claude Code יצר יש את התוכן המקורי של אובייקטים שהוחלפו

אם המאגר שלכם משתמש ב-git replace, הקבצים ב-worktree ש-Claude Code יוצר מחזיקים בתוכן האובייקטים המקוריים ולא בהחלפות שרשומות refs/replace/ שלכם מציינות. Claude Code מריץ את פקודות ה-git שעושות checkout לקבצי ה-worktree עם GIT_NO_REPLACE_OBJECTS=1, ומתעלם מכל ערך שייצאתם למשתנה הזה.

כדי לקבל את התוכן שהוחלף, צרו את ה-worktree בעצמכם עם git worktree add והפעילו את Claude Code בתוכו.

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

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

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

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

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

• 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 הגלובליות שלכם לא מפעיל את זה.
• Git was not run: the repository's own git config sets <key>: ההודעה מציינת מפתח שמפנה את Git LFS לתוכנית להרצה, כגון lfs.customtransfer.<name>.path או lfs.standalonetransferagent. אם ההגדרה שלכם, העבירו אותה להגדרות ה-git הגלובליות. אם אינכם מזהים אותה, הסירו אותה מהגדרות ה-git של המאגר, כי כלי או checkout שאינכם סומכים עליו אולי כתב אותה. נסו שוב אחרי שהמפתח הוסר מהגדרות המאגר.

#יצירת worktree נכשלת ב-partial clone

שגיאה שמכילה This repository is a partial clone אומרת ש-Claude Code לא הצליח למשוך כל אובייקט git שה-commit ההתחלתי של ה-worktree צריך. בצעו את הצעד במשפט ההודעה שמסתיים ב-try again. אחר כך נסו שוב מה-shell שבו ביצעתם אותו: הריצו claude --worktree, או הפעילו שם claude ובקשו שוב.

#Can only use --worktree in a git repository

השגיאה הזו אומרת שהעברתם --worktree בתיקייה שאינה checkout של git, ואין hook של WorktreeCreate פעיל.

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

#תיקיית ה-worktree belongs to a different repository

השגיאות belongs to a different repository ו-is a leftover worktree אומרות שתיהן ש-git קושר את התיקייה של שם ה-worktree שהעברתם למיקום אחר. זה יכול לקרות אחרי שמעתיקים או מעבירים פרויקט.

העבירו שם worktree אחר. אם בתיקייה אין עבודה שצריך לשמור ולא העתקתם או העברתם פרויקט, אפשר להסיר אותה ולנסות שוב את אותו שם. אחרי העתקה או העברה, הניסיון החוזר יכול להיכשל עם is already checked out elsewhere in this repository, לכן השתמשו בשם אחר.

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

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

ברוב המקרים שאר ההודעה אומר שמטא-נתוני ה-git של התיקייה נפתרים אל ה-checkout הראשי: למשל, קובץ ה-.git שלה מצביע אל תיקיית .git של המאגר הראשי עצמו, או ש-git פותר את עץ העבודה שלה אל ה-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 שלו, ונסו שוב.

  לפני v2.1.302, עם git 2.56 או חדש יותר, הסיומת could not be resolved הופיעה גם כשה-<path> אחרי the protected checkout החזיק קובץ .git תועה. תועה כאן אומר שהנתיב בשורת gitdir: של הקובץ הזה לא מוביל למאגר git תקין. כדי לשחזר, עדכנו את Claude Code ונסו שוב. כשנתיב ה-gitdir: הזה כבר לא קיים, אפשר גם למחוק את קובץ ה-.git ולנסות שוב.

• אומרת its recorded path has a network spelling: Claude Code אף פעם לא מחדש אל worktree בנתיב רשת. צרו את ה-worktree מחדש בנתיב מקומי.

• כל סיומת אחרת: ההודעה מציינת את הבעיה ואת התיקון שלה, כגון הסרת הפניה של core.worktree או יצירה מחדש של ה-worktree. פעלו לפיה. לפני מחיקת תיקייה שההודעה שלה אומרת שזהות ה-git שלה לא אומתה, טפלו קודם בסיבה שצוינה, למשל קישור סימבולי בנתיב ה-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 עם subtype 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.

בתוצאת stream-json, startup_failure_reason הוא worktree_unverified עבור שגיאת could not verify worktree ו-worktree_resume_refused עבור שגיאות cannot resume into worktree ו-The worktree binding is kept. יישום יכול להסתעף לפי זה במקום להתאים את טקסט השגיאה. לפני v2.1.274, לתוצאה לא היה שדה startup_failure_reason.

#ראו גם

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

• Subagents: האצלת עבודה לסוכנים מבודדים בתוך סשן
• Cross-session messaging: לאפשר לסשנים ב-worktrees שלכם להעביר ממצאים זה לזה
• Agent teams: תיאום כמה סשנים של Claude באופן אוטומטי
• Manage sessions: מתן שם, חידוש ומעבר בין שיחות
• Run a Desktop session in its own worktree: סשנים שמגובים ב-worktree ביישום שולחן העבודה