Eseguire sessioni parallele con worktrees

​

Avviare Claude in un worktree

claude --worktree feature-auth

​

Configurare l’ambiente del worktree

​

Chiedere a Claude di creare un worktree

​

Pulire i worktree

• 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 in modo da poter tornare in seguito. Rimuovere elimina la directory del worktree e il suo branch, insieme a tutto il lavoro in essi
• 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

​

Riprendere una sessione di worktree

• Directory di lancio: riprendete 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.

​

Come Claude Code applica l’isolamento

• Modifiche ai file: Claude Code blocca un Edit, Write, o NotebookEdit che ha come target un percorso nel checkout principale.
• 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.

​

Isolare i subagent con 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.

​

Pulire i worktree dei subagent e della sessione in background

• 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.

​

Personalizzare la creazione del worktree

​

Scegliere il branch di base

• "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.

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

​

Diramazione da una pull request

claude --worktree "#1234"

• 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

​

Copiare file gitignored nei worktree

.env
.env.local
config/secrets.json

​

Riutilizzare un nome di worktree

• 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.

• 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

​

Cosa i worktree condividono con il checkout principale

• La directory .git del repository: i comandi git in un worktree scrivono nella directory .git condivisa del repository principale, e il sandboxing consente quelle scritture, quindi comandi come git commit funzionano da dentro un worktree con la sandbox abilitata.
• 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. Richiede Claude Code v2.1.200 o successivo.
• 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, quindi 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. Prima della v2.1.211, un’approvazione concessa in un worktree era salvata all’interno di quel worktree, non si applicava altrove, e era persa quando il worktree era rimosso. Vedere dove le approvazioni sono salvate.
• 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.

​

Gestire i worktree manualmente

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

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

cd ../project-feature-a
claude

git worktree list

git worktree remove ../project-feature-a

​

Controllo versione non-git

{
  "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\"'"
          }
        ]
      }
    ]
  }
}

​

Risoluzione dei problemi

​

Claude Code non può entrare nel worktree all’avvio

​

La creazione del worktree fallisce su un percorso symlinked

​

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

• 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.

​

Claude Code rifiuta di usare un worktree

• 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.
• 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

• 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

​

Vedere anche

• Subagent: delegare il lavoro ad agenti isolati all’interno di una sessione
• Messaggistica tra sessioni: lasciare che le sessioni nei vostri worktree si passino i risultati
• Team di agenti: coordinare più sessioni di Claude automaticamente
• Gestire le sessioni: nominare, riprendere, e passare tra conversazioni
• Sessioni parallele desktop: sessioni supportate da worktree nell’app desktop