Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Un git worktree è una directory di lavoro separata con i propri file e branch, che condivide la stessa cronologia del repository e il remote come il vostro checkout principale. Eseguire ogni sessione di Claude Code nel proprio worktree significa che le modifiche in una sessione non toccheranno mai i file in un’altra, quindi potete avere Claude che costruisce una funzionalità in un terminale mentre corregge un bug in un secondo. Questa pagina copre l’isolamento dei worktree nella CLI. Tutto quanto segue presuppone un repository git. Per altri sistemi di controllo versione, vedere Controllo versione non-git. L’app desktop crea un worktree per ogni nuova sessione automaticamente. I worktree sono uno dei diversi modi per eseguire Claude in parallelo. Isolano le modifiche ai file, mentre i subagent e i team di agenti coordinano il lavoro stesso. Vedere Eseguire agenti in parallelo per confrontare gli approcci, o saltare direttamente a Isolare i subagent con worktrees per utilizzare worktree e subagent insieme.

​
Avviare Claude in un worktree

Passate --worktree o -w per creare un worktree isolato e avviare Claude in esso. Per impostazione predefinita, il worktree viene creato sotto .claude/worktrees/<value>/ nella radice del vostro repository, su un nuovo branch denominato worktree-<value>: 
claude --worktree feature-auth
Per mettere i worktree altrove, configurate un hook WorktreeCreate. Eseguite il comando di nuovo con un nome diverso in un altro terminale per avviare una seconda sessione isolata: 
claude --worktree bugfix-123
Se omettete il nome, Claude ne genera uno come bright-running-fox: 
claude --worktree
Potete anche chiedere a Claude di “lavorare in un worktree” durante una sessione, e creerà uno con lo strumento EnterWorktree. Prima di utilizzare --worktree in una directory per la prima volta, accettate la finestra di dialogo di fiducia dell’area di lavoro eseguendo claude una volta in quella directory. Se la fiducia non è stata ancora accettata, --worktree esce con un errore e vi chiede di eseguire claude nella directory per primo, anche quando combinato con -p.
Aggiungete .claude/worktrees/ al vostro .gitignore in modo che i contenuti del worktree non appaiano come file non tracciati nel vostro checkout principale.

​
Scegliere il branch di base

I worktree si diramano dal branch predefinito del vostro repository, origin/HEAD, quindi iniziano da un albero pulito che corrisponde al remote. Se nessun remote è configurato o il fetch fallisce, il worktree ricade al vostro HEAD locale corrente. Per diramarvisi sempre dal HEAD locale, impostate worktree.baseRef a "head" nelle impostazioni. Impostare baseRef a "head" fa sì che i nuovi worktree portino i vostri commit non spinti e lo stato del feature-branch, il che è utile quando si isolano i subagent che devono operare su lavori in corso. L’impostazione accetta solo "fresh" o "head", non ref git arbitrari: 
{
  "worktree": {
    "baseRef": "head"
  }
}
Per diramarvisi da una pull request specifica, passate il numero della PR con il prefisso #, o un URL completo della pull request di GitHub. Claude Code recupera pull/<number>/head da origin e crea il worktree in .claude/worktrees/pr-<number>: 
claude --worktree "#1234"
Per il controllo completo su come vengono creati i worktree, configurate un hook WorktreeCreate, che sostituisce completamente la logica predefinita di git worktree.

​
Copiare file gitignored nei worktrees

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. Questo .worktreeinclude copia due file env e una configurazione di segreti in ogni nuovo worktree:
.worktreeinclude
.env
.env.local
config/secrets.json
Questo si applica ai worktree creati con --worktree, worktree dei subagent, e sessioni parallele nell’app desktop.

​
Isolare i subagent con worktrees

I subagent possono eseguire nei propri worktree in modo che le modifiche parallele non entrino in conflitto. Chiedete a Claude di “usare worktree per i vostri agenti”, o impostatelo permanentemente su un subagent personalizzato aggiungendo isolation: worktree al frontmatter. Ogni subagent ottiene un worktree temporaneo che viene rimosso automaticamente quando il subagent finisce senza modifiche.

​
Pulire i worktrees

Quando uscite da una sessione di worktree, la pulizia dipende dal fatto che abbiate apportato modifiche:
  • Nessuna modifica: il worktree e il suo branch vengono rimossi automaticamente
  • Modifiche o commit esistono: Claude vi chiede di mantenere o rimuovere il worktree. Mantenere preserva la directory e il branch in modo da poter tornare in seguito. Rimuovere elimina la directory del worktree e il suo branch, scartando tutte le modifiche non committate e i commit
  • Esecuzioni non interattive: i worktree creati con --worktree insieme a -p non vengono puliti automaticamente poiché non c’è un prompt di uscita. Rimuoveteli con git worktree remove
I worktree dei subagent orfani da un crash o da un’esecuzione interrotta vengono rimossi all’avvio una volta che sono più vecchi della vostra impostazione cleanupPeriodDays, a condizione che non abbiano modifiche non committate, nessun file non tracciato e nessun commit non spinto. I worktree che create con --worktree non vengono mai rimossi da questa scansione.

​
Gestire i worktrees manualmente

Per il controllo completo sulla posizione del worktree e sulla configurazione del branch, create i worktree direttamente con Git. Questo è utile quando dovete controllare un branch esistente specifico o posizionare il worktree al di fuori del repository. Create un worktree su un nuovo branch: 
git worktree add ../project-feature-a -b feature-a
Create un worktree da un branch esistente: 
git worktree add ../project-bugfix bugfix-123
Avviate Claude nel worktree: 
cd ../project-feature-a && claude
Elencate i vostri worktree: 
git worktree list
Rimuovete uno quando avete finito: 
git worktree remove ../project-feature-a
Vedere la documentazione di Git worktree per il riferimento completo dei comandi. Ricordate di inizializzare il vostro ambiente di sviluppo in ogni nuovo worktree: installate le dipendenze, configurate gli ambienti virtuali, o eseguite qualunque cosa il vostro progetto richieda.

​
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 da stdin, 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: 
{
  "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\"'"
          }
        ]
      }
    ]
  }
}
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.

​
Vedere anche

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