Un worktree Git è una cartella di lavoro separata collegata allo stesso repository: in Cursor permette agli agenti di lavorare su checkout distinti, ma non elimina il merge né i possibili conflitti tra branch. La separazione riduce le interferenze nella cartella condivisa; integrare e controllare le modifiche resta un passaggio a parte.
Un worktree separa il lavoro mentre procede; non decide come combinare i branch quando è finito.
Che cosa isolano i worktree e cosa succede al merge
Ogni agente può lavorare nella propria cartella e nel proprio branch, invece di modificare la stessa copia dei file. Due branch, però, possono intervenire sullo stesso codice. Se cambiano righe sovrapposte, Git può richiedere una risoluzione manuale; le modifiche non sovrapposte possono invece essere combinate automaticamente.
Anche un merge senza conflitti testuali va controllato: per esempio, il codice può rinominare una funzione mentre un altro punto continua a chiamarla con il vecchio nome. Git unisce le modifiche, ma il risultato può non funzionare. Revisione e test restano quindi importanti dopo l’integrazione. Il manuale Git sui conflitti di merge descrive entrambi i casi.
Worktree di Cursor: Agents Window, IDE e configurazione
Cursor offre i worktree nativi nell’Agents Window; nell’IDE documenta invece i Worktree Skills, tra cui /worktree, /best-of-n, /apply-worktree e /delete-worktree. Con /best-of-n, le diverse esecuzioni restano in worktree separati per il confronto: Cursor non ne unisce automaticamente le modifiche, quindi spetta a te scegliere e applicare un risultato.
Per personalizzare la preparazione dell’ambiente, il file .cursor/worktrees.json accetta configurazioni generiche o specifiche per Unix e Windows. Può contenere comandi eseguiti in sequenza oppure il percorso di uno script. Cursor cerca il file prima nella cartella del worktree e poi nella radice del progetto. I dettagli dei flussi e della configurazione sono nella documentazione ufficiale di Cursor sui worktree.
La pulizia può includere i worktree creati manualmente
Da Cursor 3.5, la documentazione indica un limite predefinito di 25 worktree per macchina e spiega che la pulizia automatica può includere anche quelli creati a mano con git worktree add. Prima di affidare modifiche non ancora integrate a un worktree, considera questa regola e verifica di aver conservato il lavoro che ti serve.
Se il cambio di worktree interrompe un agente
Il 10 settembre 2026, lo staff di Cursor ha spiegato che la creazione di un worktree e il cambio della cartella radice durante un’attività possono interrompere un turno dell’agente. Come soluzione per il caso descritto, ha consigliato di avviare l’agente direttamente nella cartella in cui deve lavorare; ha anche indicato che il comando “continue” riprende un’attività interrotta. La risposta dello staff Cursor riporta questa indicazione datata.
