Vai al contenuto principale
Un git worktree è una directory di lavoro separata con i propri file e branch, che condivide la stessa cronologia del repository e lo stesso remote del tuo checkout principale. Eseguire ogni sessione di Claude Code nel proprio worktree le fornisce una copia separata dei file da modificare, quindi una sessione può sviluppare una funzionalità mentre una seconda corregge un bug.
Se utilizzi un altro sistema di controllo versione o l’app desktop, segui le istruzioni per la tua configurazione:
I worktree sono uno dei diversi modi per eseguire Claude in parallelo. Isolano le modifiche ai file. I subagent dividono il lavoro all’interno di una sessione, e la messaggistica tra sessioni consente a Claude di passare i risultati tra le sessioni nei vostri worktree. Vedere Eseguire agenti in parallelo per confrontare gli approcci, o saltare direttamente a Isolare i subagent con worktrees per utilizzare worktree e subagent insieme. La maggior parte delle sessioni ha bisogno solo delle prime due sezioni: avviare Claude in un worktree, quindi pulire quando uscite. Tornate al resto della pagina quando dovete riprendere una sessione, cambiare come vengono creati i worktree, o eseguire il debug di un errore.

​
Avviare Claude in un worktree

Passate --worktree o -w con un nome per creare un worktree isolato e avviare Claude in esso. Per impostazione predefinita, il worktree viene creato sotto .claude/worktrees/<name>/ nella radice del vostro repository, su un nuovo branch denominato worktree-<name>:
Eseguite il comando di nuovo con un nome diverso in un altro terminale per avviare una seconda sessione isolata. Se omettete il nome, Claude ne genera uno come bright-running-fox. Le esecuzioni interattive richiedono fiducia dell’area di lavoro: se non avete mai eseguito Claude nella directory prima, eseguite claude una volta lì per accettare la finestra di dialogo di fiducia, oppure --worktree esce con un errore che vi chiede di farlo. Le esecuzioni non interattive con -p saltano il controllo di fiducia, quindi claude -p --worktree procede senza di esso.
Aggiungete .claude/worktrees/ al vostro .gitignore in modo che i contenuti del worktree non appaiano come file non tracciati nel vostro checkout principale.

​
Configurare l’ambiente del worktree

Un worktree è un checkout fresco, quindi inizializzate il vostro ambiente di sviluppo lì: chiedete a Claude di installare le dipendenze, oppure eseguite il setup del vostro progetto voi stessi nella directory del worktree sotto .claude/worktrees/. Per portare file gitignored come .env in ogni nuovo worktree automaticamente, aggiungete un file .worktreeinclude.

​
Chiedere a Claude di creare un worktree

Puoi anche chiedere a Claude di “lavorare in un worktree” durante una sessione, e ne creerà uno con lo strumento EnterWorktree. Una volta in un worktree, Claude può passare direttamente a un altro sotto .claude/worktrees/ chiamando EnterWorktree con il percorso di destinazione; il worktree precedente rimane su disco intatto. Quando Claude entra in un percorso al di fuori della directory .claude/worktrees/ del repository, Claude Code chiede prima la tua approvazione. Lo spostamento porta in quella posizione la directory di lavoro della sessione, l’accesso in scrittura e la configurazione del progetto come CLAUDE.md e le impostazioni. Una regola di permesso EnterWorktree o la scelta di “non chiedere di nuovo” non sopprime questa richiesta; solo la modalità bypassPermissions la salta.
I percorsi degli hook non seguono il worktree. Dopo che Claude entra in un worktree, Claude Code mantiene ${CLAUDE_PROJECT_DIR} nei vostri hook dove era e passa il percorso del worktree a loro in un modo diverso:
  • ${CLAUDE_PROJECT_DIR} rimane fermo: punta ancora alla radice del progetto dove la sessione è iniziata, quindi un comando hook come ${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh esegue ancora lo script nel checkout principale.
  • cwd segue Claude: il campo cwd nel JSON di input dell’hook è la radice del worktree, e si sposta di nuovo quando Claude esegue cd. Leggetelo quando un hook ha bisogno del percorso del worktree.

​
Claude non ha lo strumento EnterWorktree

Se chiedi a Claude di lavorare in un worktree e non ha lo strumento EnterWorktree o ExitWorktree, verifica se permissions.blockWritesOutsideWorkingDirectories è attiva. Quando la chiave è attiva, Claude Code rimuove entrambi gli strumenti per i worktree o rifiuta le chiamate a essi. Puoi continuare a lavorare nei worktree mentre la chiave è attiva:
  • Sessioni interattive: avvia la sessione in un worktree con claude --worktree.
  • Sessioni in background: Claude Code rifiuta le modifiche di una sessione in background nel tuo checkout principale finché la sessione non chiama EnterWorktree, che non ha a disposizione. Una qualsiasi di queste opzioni consente alla sessione di apportare modifiche:
    • Avviala con claude --bg --worktree
    • Imposta worktree.bgIsolation su "none"
    • Fai in modo che Claude apporti modifiche in un worktree creato con git worktree add sotto la directory in cui è iniziata la sessione
Per riavere gli strumenti, esegui /status nella sessione per elencare le fonti di impostazioni che ha caricato e rimuovi la chiave da ogni file che la imposta. Poi riavvia Claude Code. Se la chiave è impostata dalle impostazioni gestite, chiedi al tuo amministratore se la policy debba essere modificata.

​
Pulire i worktree

Quando uscite da una sessione di worktree interattiva, Claude controlla il worktree per il lavoro che la rimozione eliminerebbe: file modificati o non tracciati, lavoro non committato all’interno di submodule estratti, e nuovi commit. Queste regole si applicano ai worktree che Claude ha creato con git. Per un worktree che il vostro hook WorktreeCreate ha creato, consultate invece WorktreeRemove.
  • Il worktree è pulito: per una sessione senza nome, Claude rimuove il worktree e il suo branch automaticamente. Una sessione denominata vi chiede prima in modo da poter mantenere il worktree per dopo
  • Il worktree ha lavoro in esso: Claude vi chiede di mantenere o rimuovere il worktree. Mantenere preserva la directory e il branch. Per tornare in seguito, eseguite il comando claude --worktree <name> --resume che Claude Code stampa all’uscita. Rimuovere elimina la directory del worktree e il suo branch, insieme a tutto il lavoro in essi
  • È estratto un altro branch: se il worktree si trova su un branch diverso dal proprio che ha commit successivi al commit iniziale del worktree, Claude ti chiede di mantenere o rimuovere il worktree. Entrambe le risposte mantengono quell’altro branch e i suoi commit. Rimuovere elimina la directory del worktree e il branch proprio del worktree, quello che Claude ha creato insieme a esso
  • Lo stato del worktree non può essere verificato: quando Claude Code non riesce a contare i cambiamenti del worktree o non riesce a ispezionare i checkout dei suoi submodule, vi chiede piuttosto che rimuovere il worktree automaticamente. Il prompt nomina ciò che non ha potuto controllare
Le esecuzioni non interattive con -p non hanno un prompt di uscita, quindi Claude non pulisce i loro worktree, e Claude Code lascia il blocco che ha preso su ognuno al momento della creazione in posizione fino a quando una scansione di blocco stale successiva della sessione lo rilascia. Per rimuoverne uno, eseguite git worktree remove; se git rifiuta perché il worktree è bloccato, eseguite prima git worktree unlock su di esso. Su Windows, rimuovere un worktree non elimina i file al di fuori di esso. Se una cartella all’interno del worktree è un collegamento a qualcos’altro, come una junction NTFS o un collegamento simbolico di directory, Claude Code elimina solo il collegamento.

​
Riprendere una sessione di worktree

Quando riprendi una sessione che era terminata all’interno di un worktree senza uscirne, Claude Code restituisce la sessione a quel worktree. Questo vale per le riprese interattive, per --continue e --resume in modalità non interattiva con -p, e per l’Agent SDK. --continue seleziona la sessione più recente registrata nella directory da cui avvii. Di nuovo all’interno del worktree, Claude può uscirne con lo strumento ExitWorktree quando la sessione dispone di quello strumento. Prima di restituire la sessione al suo worktree, Claude Code verifica che il worktree sia ancora un checkout separato da quello principale, e rifiuta di rientrare in un worktree che fallisce il controllo. Per un git worktree, il controllo legge i suoi metadati git. Un worktree senza metadati git, come uno che un hook WorktreeCreate ha creato, può passare il controllo; i casi che Claude Code ancora rifiuta sono elencati con i loro recuperi sotto Claude Code rifiuta di usare un worktree. Per i messaggi e come recuperare da ognuno, vedere La sessione riprende al di fuori del suo worktree. Dove lanciate da, e come riprendete, cambiano cosa Claude Code rientra:
  • Directory di lancio: riprendete con --resume dal checkout principale o da un’altra directory del repository. Claude Code rientra in un worktree che ha creato con git sotto .claude/worktrees/ anche quando lanciate da dentro di esso. Quando lanciate da dentro qualsiasi altro worktree, Claude Code rientra in esso solo se può garantirlo da lì: un worktree che è il suo proprio repository, uno senza metadati git, o un lancio da una sottodirectory di un worktree che avete creato con git worktree add rifiuta, quindi lanciate quelli dal checkout principale.
  • --fork-session: la sessione biforcata inizia nella directory da cui avete lanciato Claude, e Claude Code lascia il worktree della sessione originale intatto.
  • Worktree eliminato: se la directory del worktree non esiste più, Claude Code riprende la sessione nella directory da cui avete lanciato Claude. Vi dice che il worktree è scomparso e cancella il binding del worktree della sessione.
Prima della v2.1.212, una ripresa non interattiva rimaneva nella directory di avvio e ExitWorktree segnalava che non c’era una sessione di worktree attiva da cui uscire.
Quando Claude entra o esce da un worktree che Claude Code ha creato con git, la trascrizione lo segue. Claude Code registra la sessione sotto la nuova directory di lavoro della sessione, nello stesso modo in cui fa /cd, quindi /desktop e --resume la trovano lì. L’uscita la riporta indietro nello stesso modo. Un worktree creato da un hook WorktreeCreate mantiene la sua trascrizione nella directory di avvio.

​
Come Claude Code applica l’isolamento

Mentre una sessione è isolata in un worktree, Claude Code blocca le chiamate di strumento che i controlli di seguito definiscono. Le stesse regole si applicano se avete avviato la sessione con --worktree, Claude è entrato in un worktree con EnterWorktree, o avete ripreso una sessione di worktree. Lo stesso enforcement copre ogni subagent che Claude genera dalla sessione isolata. Si applica se la sessione è interattiva o viene eseguita in background. I subagent che vengono eseguiti nel loro proprio worktree portano gli stessi controlli. La loro cronologia delle versioni è sotto Scrivere file di subagent. Claude Code applica quattro controlli:
  • Modifiche ai file: Claude Code blocca un Edit, Write, o NotebookEdit che ha come target un percorso nel checkout principale. Per modificare un file nel checkout principale, modificalo tu stesso o avvia lì una sessione interattiva.
  • Directory di lavoro del comando: Claude Code blocca un comando Bash, PowerShell, o Monitor la cui directory di lavoro si risolve nel checkout principale, o la cui directory di lavoro non può verificare che rimanga al di fuori di esso.
  • Reindirizzamenti git: Claude Code blocca un comando Bash o Monitor che reindirizza git nel checkout principale. Il reindirizzamento può provenire attraverso git -C, --git-dir, una variabile GIT_DIR o GIT_WORK_TREE, o un cd nel checkout principale prima di eseguire git.
  • Forma del comando: Claude Code blocca un comando Bash o Monitor quando non può verificare dal testo del comando che qualsiasi git che il comando esegue rimane all’interno del worktree. Questo accade, ad esempio, quando il nome del comando è calcolato a runtime, quando la sintassi non può essere analizzata, o quando un’espansione come ${!name} o ${ command; } potrebbe eseguire un comando che il testo non esplicita. Claude Code dice a Claude come riscrivere il comando rifiutato, come dividerlo in comandi semplici e separati. Non potete disattivare questo controllo.
Questi controlli leggono il percorso a cui è destinata una modifica, la directory in cui viene eseguito un comando e il testo del comando. Nessuno di essi tiene traccia di quali file scrive un comando della shell, quindi un comando che scrive nel checkout principale senza eseguirvi git, come cp o un reindirizzamento della shell, non viene rifiutato da questi controlli. Claude Code tratta quel comando come qualsiasi altro comando della shell, in base alle tue impostazioni di permessi e sandboxing. I controlli si applicano al repository da cui avete lanciato Claude Code. Coprono anche il checkout principale da cui un worktree collegato è collegato. Per i comandi PowerShell, Claude Code applica solo il controllo della directory di lavoro. Claude vede ogni rifiuto come un errore di strumento che nomina il worktree e dice come procedere. Per un comando rifiutato, consultate cosa significa il messaggio di rifiuto e come cancellarlo.

​
Isolare i subagent con worktree

I subagent possono eseguire nei loro propri worktree in modo che le modifiche parallele non entrino in conflitto. Chiedete a Claude di “usare worktree per i vostri agenti”, o rendete l’isolamento permanente per un subagent personalizzato aggiungendo isolation: worktree al suo frontmatter. Questo subagent in .claude/agents/ viene sempre eseguito nel suo proprio worktree:
Ogni subagent ottiene un worktree temporaneo che Claude Code rimuove automaticamente quando il subagent finisce senza modifiche; un worktree con modifiche rimane su disco fino a quando la scansione periodica di seguito può rimuoverlo senza perdere lavoro. Per un worktree creato dal tuo hook WorktreeCreate, consulta invece WorktreeRemove. I worktree dei subagent utilizzano lo stesso branch di base di --worktree, quindi si diramano dal branch predefinito del vostro repository a meno che worktree.baseRef non sia impostato su "head". Un subagent nel proprio worktree prende i file di istruzioni con cui viene avviato dalla tua conversazione principale, non dal suo worktree. Quando quel worktree si trova nella posizione predefinita in .claude/worktrees/, il subagent inoltre non carica il file CLAUDE.md o la directory .claude/rules/ nella radice del worktree mentre legge i file lì, anche se differiscono nel branch del worktree.

​
Pulire i worktree dei subagent e della sessione in background

Claude Code esegue una scansione periodica che rimuove i worktree che Claude ha creato per i subagent e le sessioni in background una volta che sono più vecchi della vostra impostazione cleanupPeriodDays, seguendo le regole della scansione di conservazione. Quando inviate in background una sessione --worktree, il suo worktree diventa un worktree di sessione in background che la scansione può rimuovere. La scansione lascia un worktree in posizione in questi casi:
  • Il worktree contiene ancora lavoro: file modificati o non tracciati, o commit non spinti.
  • Un submodule estratto nel worktree contiene file modificati o non tracciati, oppure Claude Code non può ispezionare i submodule del worktree. Questo controllo richiede Claude Code v2.1.274 o successivo.
  • Uno dei quattro casi che bloccano anche la creazione del worktree si applica: Claude Code non può determinare quali driver di filtro la configurazione del repository definisce, o trova un’impostazione lì che non può disattivare.
  • Il worktree appartiene a una sessione --worktree che non avete inviato in background, indipendentemente dalla sua età.
  • Avete creato il worktree voi stessi con git worktree add, anche se poi avete eseguito una sessione --worktree <name> in esso e l’avete inviata in background.
Claude Code scrive un marcatore nei metadati git di ogni worktree che crea con git, e la scansione mantiene qualsiasi worktree senza uno, incluso un worktree che un hook WorktreeCreate ha creato.

​
Blocchi dei worktree e rimozione manuale

Mentre un agente è in esecuzione, Claude Code mantiene un git worktree lock sul suo worktree in modo che la pulizia concorrente non possa rimuoverlo, e rilascia il blocco quando l’agente finisce. Claude Code mantiene lo stesso blocco sul worktree che ha creato per una sessione inviata in background mentre la sessione viene eseguita, quindi la scansione lascia il worktree in posizione e git worktree remove rifiuta di rimuoverlo. La scansione rilascia anche un blocco che Claude Code ha impostato per una sessione il cui processo è uscito, quindi una sessione in background uccisa non lascia il suo worktree permanentemente bloccato. La scansione non rilascia mai un blocco che hai impostato tu stesso con git worktree lock. Per pulire un worktree che la scansione mantiene, eseguite git worktree remove, aggiungendo --force se il worktree ha modifiche non committate o file non tracciati. Se git rifiuta perché il worktree è bloccato, eseguite prima git worktree unlock su di esso.

​
Personalizzare la creazione del worktree

I valori predefiniti di Claude Code per la creazione di worktree coprono la maggior parte delle sessioni: li crea sotto .claude/worktrees/, li dirama dal branch predefinito del vostro repository, e controlla solo i file tracciati. Le opzioni in questa sezione cambiano quei valori predefiniti.

​
Scegliere il branch di base

I nuovi worktree si diramano dal branch predefinito del repository, quindi la maggior parte delle sessioni non ha bisogno di questa impostazione. Impostate worktree.baseRef nelle impostazioni per diramarvisi dal vostro lavoro corrente. L’impostazione accetta due valori:
  • "fresh" (predefinito): dirama dal branch predefinito del repository sul remote, solitamente main, quindi il worktree inizia da un albero pulito che corrisponde al remote.
  • "head": dirama dal vostro HEAD locale corrente, quindi il worktree porta i vostri commit non spinti e lo stato del feature-branch. Usate questo quando isolate i subagent che devono operare su lavori in corso. All’interno di un worktree, "head" si risolve in HEAD di quel worktree, non nel checkout principale.
Non potete impostare worktree.baseRef a un nome di branch. Per avviare un worktree da un branch esistente specifico, createlo con git direttamente. Per una base "fresh", Claude Code mantiene origin/HEAD aggiornato:
  • Quando il repository non è stato sottoposto a fetch nelle ultime 24 ore, esegue il fetch del branch predefinito, con un limite di cinque secondi, e utilizza il ref memorizzato nella cache locale se il fetch fallisce.
  • Il fetch non attende mai input nel tuo terminale. Viene considerato fallito anche quando git o ssh chiederebbero una password, una passphrase della chiave o la conferma di un nuovo host SSH.
  • Se nessun remote è configurato, oppure origin/HEAD non è memorizzato nella cache locale e non è possibile recuperarlo, il worktree ricade sul tuo HEAD locale corrente.
Questo esempio fa sì che ogni nuovo worktree si dirama dal vostro lavoro corrente:

​
Diramazione da una pull request

Per diramarvisi da una pull request o merge request specifica, passate a --worktree il numero con prefisso #, un URL di pull request di GitHub, o un URL di merge request di GitLab come https://gitlab.com/group/repo/-/merge_requests/123. Claude Code recupera il commit head di quel cambiamento da origin e crea il worktree in .claude/worktrees/pr-<number>. Quotate l’argomento in modo che la vostra shell non tratti # come l’inizio di un commento:
Claude Code legge solo il numero dall’URL. Recupera sempre da origin del vostro repository, e sceglie il percorso di recupero dall’host di origin:
  • github.com: recupera pull/<number>/head
  • gitlab.com: recupera merge-requests/<number>/head
  • GitHub Enterprise, GitLab auto-gestito, o qualsiasi altro host: prova prima pull/<number>/head, poi merge-requests/<number>/head
Questo fetch non attende mai input nel tuo terminale. Se git o ssh chiederebbero una password, una passphrase della chiave o la conferma di un nuovo host SSH, il fetch invece fallisce e Claude Code termina con il messaggio Error creating worktree: Failed to fetch PR/MR #<number>. Una chiave gestita da ssh-agent funziona comunque, quindi carica lì la tua chiave ed esegui manualmente git fetch una volta per registrare un nuovo host prima di iniziare. Prima della v2.1.233, Claude Code accettava solo #<number> e URL di pull request in stile GitHub per --worktree, e recuperava sempre pull/<number>/head.

​
Copiare file gitignored nei worktree

Un worktree è un checkout fresco, quindi i file non tracciati come .env o .env.local dal vostro repository principale non sono presenti. Per copiarli automaticamente quando Claude crea un worktree, aggiungete un file .worktreeinclude alla radice del vostro progetto. Il file utilizza la sintassi .gitignore. Solo i file che corrispondono a un pattern e sono anche gitignored vengono copiati, quindi i file tracciati non vengono mai duplicati. Se scrivete un pattern che inizia con **/ e i file che volete sono all’interno di una directory che è gitignored nel suo insieme, Claude Code li copia solo quando quella directory stessa corrisponde al pattern, o quando il primo nome dopo **/ è uno dei nomi nel percorso della directory. Ad esempio, se scrivete **/.claude/skills/*.md, quel primo nome è .claude, quindi Claude Code copia i file corrispondenti da una directory .claude/ ignorata. Per copiare file da una directory ignorata che un pattern **/ non raggiunge, nominate la directory nel pattern: scrivete vendor/**/config.json piuttosto che **/config.json. Prima della v2.1.239, Claude Code copiava file da una directory completamente ignorata per un pattern **/ solo quando la directory stessa corrispondeva al pattern. Questo .worktreeinclude copia due file env e una configurazione di segreti in ogni nuovo worktree:
.worktreeinclude
Questo si applica a ogni worktree che Claude Code crea con git: worktree --worktree, worktree dei subagent, e sessioni parallele nell’app desktop. Con un hook WorktreeCreate, copiate i file all’interno dello script dell’hook.

​
Riutilizzare un nome di worktree

Se esiste già un worktree con il nome che passi a --worktree, Claude Code lo apre invece di crearne uno nuovo. Se Claude Code si interrompe con un errore contenente belongs to a different repository o is a leftover worktree, consulta La directory del worktree belongs to a different repository. Con la base predefinita "fresh", un worktree riaperto si reimposta sul branch predefinito del repository invece di continuare dal suo vecchio tip quando sono soddisfatte tutte le seguenti condizioni:
  • Non ha modifiche non committate o file non tracciati.
  • È ancora sul branch che Claude Code ha creato per esso.
  • Non ha commit propri, o la sua pull request o merge request è stata unita e il suo branch remoto è stato eliminato.
Claude Code rileva il caso unito dallo stato git da solo: il branch remoto a cui il worktree ha spinto non esiste più, e ogni commit nel worktree è già sul branch predefinito. In ogni altro caso, Claude Code riapre il worktree al suo vecchio tip:
  • Il worktree fallisce una qualsiasi delle condizioni.
  • Claude Code non può verificare lo stato del worktree.
  • worktree.baseRef è "head".
  • Il nome è un riferimento a una pull request o merge request.

​
Sostituire la creazione del worktree con un hook

Configurate un hook WorktreeCreate per sostituire completamente la logica predefinita di git worktree, incluso il posizionamento dei worktree da qualche parte diverso da .claude/worktrees/. Per un esempio completo, vedere Controllo versione non-git.

​
Cosa i worktree condividono con il checkout principale

Un worktree ottiene i suoi propri file e branch, ma condivide quanto segue con il checkout principale:
  • La directory .git del repository: i comandi git in un worktree scrivono nella directory .git condivisa del repository principale. Con la sandbox abilitata, comandi come git commit funzionano in una sessione alla radice del worktree, che è dove --worktree ne avvia una. Per impostazione predefinita, non riescono con un errore index.lock se esegui claude in una sottodirectory del worktree.
  • Plugin: i plugin installati a ambito del progetto dal checkout principale caricano anche nei worktree dello stesso repository, quindi non è necessario reinstallarli per ogni worktree.
  • Approvazioni di permesso: scegliere “Sì, e non chiedere di nuovo” per un comando Bash in una sessione di worktree salva la regola nel .claude/settings.local.json del checkout principale. La regola si applica nel checkout principale e in ogni altro worktree del repository, e sopravvive alla rimozione del worktree. Su Windows e negli altri casi in cui Claude Code non utilizza la radice del repository, la regola rimane con quel worktree. Consulta dove vengono salvate le approvazioni.
  • Skill, agenti e comandi non tracciati: quando il checkout del worktree non ha una directory .claude/skills alla sua radice, ad esempio perché il vostro .claude/skills è gitignored, Claude Code carica le skill del progetto del checkout principale nella sessione del worktree. In un worktree con la sua propria directory .claude/skills, carica solo quella copia. Lo stesso read-through copre .claude/agents e .claude/commands. Per le skill, il read-through richiede Claude Code v2.1.277 o successivo.
Tutti questi si applicano indipendentemente dal fatto che tu crei il worktree con --worktree o con git worktree add. In una sessione di worktree che avvii dall’app desktop, Claude Code legge la configurazione del progetto, come impostazioni, hook, skill, agenti, comandi e server .mcp.json, dalla radice del checkout principale. I comandi degli hook vengono eseguiti in quella radice e ${CLAUDE_PROJECT_DIR} punta a essa. Per raggiungere i file su cui Claude sta lavorando, leggi il percorso del worktree dal campo di input cwd dell’hook. I file CLAUDE.md e .claude/rules/ vengono comunque caricati dal worktree.

​
Gestire i worktree manualmente

Create i worktree con Git direttamente quando dovete controllare un branch esistente specifico o posizionare il worktree al di fuori del repository. Create un worktree su un nuovo branch:
Create un worktree da un branch esistente, sostituendo fix-issue-456 con un branch che esiste già nel vostro repository:
Avviate Claude nel worktree:
Elencate i vostri worktree:
Rimuovete uno quando avete finito:
Vedere la documentazione di Git worktree per il riferimento completo dei comandi.

​
Controllo versione non-git

L’isolamento dei worktree utilizza git per impostazione predefinita. Per SVN, Perforce, Mercurial, o altri sistemi, configurate gli hook WorktreeCreate e WorktreeRemove per fornire logica di creazione e pulizia personalizzata. Poiché l’hook sostituisce il comportamento predefinito di git, .worktreeinclude non viene elaborato quando utilizzate --worktree. Copiate i file di configurazione locali all’interno dello script dell’hook. Questo hook WorktreeCreate legge il nome del worktree dal JSON su stdin con jq, controlla una copia di lavoro SVN fresca, e stampa il percorso della directory in modo che Claude Code possa usarlo come directory di lavoro della sessione. Aggiungete la configurazione al vostro settings.json:
Abbinarlo a un hook WorktreeRemove per pulire quando la sessione termina. Vedere il riferimento degli hook per lo schema di input e un esempio di rimozione. Un hook WorktreeCreate vi consente anche di eseguire /batch al di fuori di un repository git. Ogni subagent /batch pubblica quindi la sua modifica con i comandi di controllo versione del vostro progetto e, quando non riesce ad aprire una pull request, segnala invece ciò che ha pubblicato. L’esecuzione di /batch al di fuori di un repository git richiede Claude Code v2.1.281 o versione successiva.

​
Risoluzione dei problemi

Claude Code segnala gli errori di seguito quando crea un worktree, entra in uno all’avvio, o restituisce una sessione ripresa a uno.

​
Claude Code non può entrare nel worktree all’avvio

Quando Claude Code non può entrare nella directory del worktree all’avvio, stampa un errore che nomina il percorso ed esce con codice 1. Questo può accadere quando un hook WorktreeCreate stampa qualcosa di diverso dalla directory che ha creato, o quando la directory è stata eliminata dopo che è stata configurata.

​
La creazione del worktree fallisce su un percorso symlinked

Claude Code rifiuta di creare un worktree quando .claude, .claude/worktrees, o la directory del worktree stesso è un symlink, e l’errore nomina il percorso symlinked. Rimuovete il symlink e riprovate. Prima della v2.1.212, se il repository conteneva già un symlink committato in uno di quei percorsi, la creazione del worktree lo seguiva e poteva creare file al di fuori del repository.

​
Un worktree creato da Claude Code ha il contenuto originale degli oggetti sostituiti

Se il tuo repository usa git replace, i file in un worktree che Claude Code crea contengono il contenuto degli oggetti originali anziché quello delle sostituzioni indicate dalle tue voci refs/replace/. Claude Code esegue i comandi git che effettuano il checkout dei file del worktree con GIT_NO_REPLACE_OBJECTS=1, ignorando qualsiasi valore che hai esportato per quella variabile. Per ottenere il contenuto sostituito, crea tu stesso il worktree con git worktree add e avvia Claude Code al suo interno.

​
I file Git LFS sono file puntatore in un worktree che Claude Code ha creato

Se configurate Git LFS con git lfs install --local, un worktree che Claude Code crea contiene file puntatore LFS invece dei file reali. Il flag --local scrive il filtro LFS nel .git/config del repository stesso piuttosto che nella vostra configurazione git globale. Un semplice git lfs install scrive nella vostra configurazione globale e non è interessato. Lo stesso si applica a qualsiasi altro driver di filtro definito nel config del repository stesso. Claude Code salta i driver di filtro del repository stesso quando crea un worktree perché un driver di filtro è un comando shell, e qualsiasi cosa che possa scrivere nel repository, incluso Claude, potrebbe averlo messo lì. Prima della v2.1.247, Claude Code eseguiva quei driver durante la creazione del worktree. Per ottenere i file reali, eseguite git lfs pull all’interno del worktree. In quattro rari casi, Claude Code non crea alcun worktree: non può dire quali driver di filtro la configurazione del repository definisce, o trova un’impostazione lì che non può disattivare. Abbinate l’errore alla sua correzione:
  • Could not read the repository git config to neutralize filter drivers: Claude Code non poteva leggere il .git/config del repository, ad esempio a causa dei suoi permessi. Riparate quello e riprovate.
  • The repository git config defines a filter driver whose name cannot be neutralized (contains "=" or a newline): rinominate o rimuovete quel driver di filtro in .git/config e riprovate.
  • The repository git config has a conditional include (includeIf): spostate le impostazioni che includeIf in .git/config estrae direttamente in quel file, rimuovete includeIf, e riprovate. Un includeIf nella vostra configurazione git globale non attiva questo.
  • Git was not run: the repository's own git config sets <key>: il messaggio nomina una chiave che punta Git LFS a un programma da eseguire, come lfs.customtransfer.<name>.path o lfs.standalonetransferagent. Se quell’impostazione è vostra, spostatela nella vostra configurazione git globale. Se non la riconoscete, rimuovetela dalla configurazione git del repository, poiché uno strumento o checkout che non fidate potrebbe averla scritta. Riprovate una volta che la chiave è scomparsa dalla configurazione del repository.

​
La creazione del worktree fallisce in un clone parziale

Un errore contenente This repository is a partial clone significa che Claude Code non è riuscito a recuperare tutti gli oggetti git di cui ha bisogno il commit di partenza del worktree. Esegui il passaggio indicato nella frase del messaggio che termina con try again. Poi riprova dalla shell in cui l’hai eseguito: esegui claude --worktree, oppure avvia claude lì e chiedi di nuovo.

​
Can only use --worktree in a git repository

Questo errore significa che hai passato --worktree in una directory che non è un checkout git, e nessun hook WorktreeCreate è attivo.
  • In una cartella senza controllo di versione, esegui lì git init, crea un primo commit, poi riprova.
  • In un checkout di un altro sistema di controllo di versione, configura l’hook suggerito dal messaggio.
  • Per lavorare direttamente nella directory, avvia Claude senza --worktree.

​
La directory del worktree belongs to a different repository

Gli errori belongs to a different repository e is a leftover worktree significano entrambi che git associa a un’altra posizione la directory per il nome del worktree che hai passato. Questo può accadere dopo aver copiato o spostato un progetto. Passa un nome di worktree diverso. Se la directory non contiene lavoro da conservare e non hai copiato né spostato un progetto, puoi rimuoverla e riprovare con lo stesso nome. Dopo una copia o uno spostamento, quel nuovo tentativo può fallire con is already checked out elsewhere in this repository, quindi usa un nome diverso.

​
Claude Code rifiuta di usare un worktree

Un errore che inizia con Refusing to use <path> as an isolation worktree significa che Claude Code ha controllato l’identità git della directory prima di adottarla come checkout isolato di una sessione o subagent, e l’ha rifiutata. Il controllo viene eseguito se Claude Code sta creando il worktree, entrando in uno esistente, o riutilizzandone uno da un’esecuzione precedente. Nella maggior parte dei casi il resto del messaggio dice che i metadati git della directory si risolvono nel checkout principale: ad esempio, il suo file .git punta alla directory .git del repository principale stesso, o git risolve il suo albero di lavoro al checkout principale attraverso un reindirizzamento core.worktree. Da una tale directory, un comando git ordinario come git reset --hard agirebbe sul checkout principale invece che sul worktree. Claude Code rifiuta anche quando la directory ha una voce .git che non può leggere, piuttosto che assumere che il worktree sia sicuro. Una directory senza metadati git affatto, come una che il vostro hook WorktreeCreate crea, passa il controllo solo quando nessun repository git la contiene. Se l’hook crea la directory all’interno di un repository, git la risolve al checkout di quel repository e Claude Code la rifiuta con il messaggio git resolves its working tree to, quindi fate in modo che l’hook crei le sue directory al di fuori di qualsiasi repository. Claude Code lascia la directory rifiutata in posizione, poiché potrebbe contenere lavoro. Abbinate il messaggio al suo recupero, se segue Refusing to use <path> o appare in un messaggio di ripresa; alcuni finali si verificano solo nei messaggi di ripresa:
  • Dice launch from the parent checkout o Run the resume from the project checkout: avete lanciato Claude Code da dentro il worktree. Lanciate dal checkout principale; il worktree non ha bisogno di ricreazione.
  • Dice it cannot be resumed or re-entered: nulla in questa sessione garantisce il worktree da dove avete lanciato. Ricreate; la directory e il suo lavoro rimangono su disco per il recupero manuale, e quando il worktree ha un checkout genitore, riprendere da lì funziona anche.
  • Dice it contains the protected checkout: la directory rifiutata è un genitore del vostro checkout principale, come la vostra home directory. Non la eliminate. Cambiate il percorso del worktree, come il percorso che il vostro hook WorktreeCreate restituisce o il target di EnterWorktree, in modo che il worktree non contenga il checkout.
  • Dice the protected checkout <path> has a .git entry that could not be examined o has git metadata that could not be resolved: il problema è nei metadati git del checkout principale, non nel worktree. Non eliminate il worktree, e ignorate il consiglio finale del messaggio di ricrearlo, che non si applica a questi due finali. Riparate il checkout principale, ad esempio un problema di permessi o un rifiuto git dubious ownership sul suo .git, e riprovate. Prima della v2.1.302, con git 2.56 o versioni successive, il finale could not be resolved compariva anche quando il <path> dopo the protected checkout conteneva un file .git spurio. Spurio qui significa che il percorso sulla riga gitdir: di quel file non porta a un repository git valido. Per risolvere, aggiorna Claude Code e riprova. Quando quel percorso gitdir: non esiste più, puoi anche eliminare il file .git e riprovare.
  • Dice its recorded path has a network spelling: Claude Code non riprende mai in un worktree a un percorso di rete. Ricreate il worktree a un percorso locale.
  • Qualsiasi altro finale: il messaggio nomina il problema e la sua correzione, come rimuovere un reindirizzamento core.worktree o ricreate il worktree; seguitelo. Prima di eliminare una directory il cui messaggio dice che la sua identità git non potrebbe essere verificata, affrontate la causa nominata prima, ad esempio un collegamento simbolico nel percorso del worktree o git stesso che non riesce a eseguire, poiché la directory potrebbe essere sana. Quando ricreate, salvate i cambiamenti di cui avete bisogno dalla vecchia directory prima; rimane su disco.

​
La sessione riprende al di fuori del suo worktree

Quando riprendete una sessione in modo interattivo e Claude Code non può restituirla al suo worktree, Claude Code lo dice con uno dei messaggi di seguito. Quando Claude Code cancella il binding del worktree, lo registra nella trascrizione della sessione. Se sopprimete le scritture della trascrizione, il messaggio dice invece che il binding non potrebbe essere cancellato e che Claude Code ricontrollerà il worktree su una ripresa successiva. In modalità non interattiva con -p, e su riprese che l’Agent SDK esegue, Claude Code interrompe la ripresa con un errore stderr per ogni rifiuto tranne un worktree scomparso, invece di continuare senza isolamento. Con --output-format stream-json, il rifiuto arriva anche su stdout come un messaggio result con sottotipo error_during_execution il cui array errors porta lo stesso testo, quindi un’applicazione Agent SDK riceve il motivo piuttosto che solo un’uscita non zero. Prima della v2.1.260, un rifiuto di ripresa del worktree non produceva alcun messaggio result. I messaggi assumono forme diverse dai messaggi interattivi nella tabella:
  • Error: cannot resume into worktree <path>: ...This session was not started. per un rifiuto che la tabella mostra come Did not re-enter. Claude Code cancella il binding del worktree prima di uscire, e l’errore lo dice; la prossima volta che riprendete la conversazione, la sessione continua nella directory corrente senza isolamento del worktree. Prima della v2.1.260, Claude Code non scriveva il binding cancellato, quindi ogni ritentativo della stessa ripresa falliva con lo stesso errore. Se sopprimete le scritture della trascrizione, il clear non può essere salvato. L’errore dice allora che lo stesso comando sarà rifiutato di nuovo, e nomina --fork-session e l’avvio di una nuova conversazione come modi per continuare senza il worktree.
  • Error: could not verify worktree <path> for this resume, so the resume was aborted... per Could not verify
  • Error: ...The worktree binding is kept. per Could not re-enter
  • Notice: the worktree <path> for this session no longer exists... per un worktree scomparso; Claude Code lo stampa e continua la sessione, come una ripresa interattiva fa
Il finale di rifiuto incorporato in ogni errore è condiviso con gli avvisi interattivi, quindi corrisponde ancora alla sua voce sotto Claude Code rifiuta di usare un worktree. Nel risultato stream-json, startup_failure_reason è worktree_unverified per l’errore could not verify worktree e worktree_resume_refused per gli errori cannot resume into worktree e The worktree binding is kept. Un’applicazione può ramificarsi su di esso invece di abbinare il testo dell’errore. Prima della v2.1.274, il risultato non portava alcun campo startup_failure_reason.

​
Vedere anche

I worktree gestiscono l’isolamento dei file. Le pagine correlate di seguito coprono la delega del lavoro in quei checkout isolati, il passaggio dei risultati tra loro, e il passaggio tra le sessioni che create: