Git worktree: lavorare in parallelo senza impazzire (e perché gli agenti AI li adorano)

Una sola copia del repository, tante working directory indipendenti: la funzionalità di Git che ha cambiato il mio modo di cambiare contesto.

C’è un momento, nella giornata di ogni sviluppatore, che conosci a memoria. Sei immerso in una feature complicata: dodici file modificati, l’IDE che ha finalmente reindicizzato tutto, il debugger fermo su un breakpoint, la testa che tiene insieme un castello mentale fragilissimo. E in quel preciso istante arriva il messaggio: “C’è un bug critico in produzione, serve un fix subito”.

Cosa fai? Le opzioni classiche sono tre, e fanno male tutte e tre. Puoi fare git stash e pregare di ricordarti cosa avevi in mano. Puoi committare un mezzo lavoro con un messaggio tipo WIP non funziona ancora che inquinerà la history. Oppure puoi clonare di nuovo il repository in un’altra cartella, aspettare il download, riconfigurare l’ambiente e ricostruire tutto da zero. In ogni caso, quel castello mentale crolla.

Esiste una quarta opzione, e da quando l’ho scoperta la uso quasi ogni giorno: i git worktree. E qui arrivo al vero motivo per cui ho scritto questo post: i worktree sono in Git da anni, eppure continuo a vedere tantissimi sviluppatori, anche bravissimi, che non li usano e nemmeno sanno che esistono. Ogni volta che li mostro a qualcuno la reazione è la stessa: “ma come ho fatto a lavorare senza fino ad oggi?”. Quindi mettiamo le cose in chiaro una volta per tutte: da dove vengono, quale problema risolvono davvero, come si usano e perché, oggi, sono diventati uno strumento fondamentale anche per gli agenti di coding basati su AI.

Da dove arrivano

Il comando git worktree è arrivato con Git 2.5, rilasciato il 27 luglio 2015. Prima di allora la regola implicita era ferrea: un repository, una working directory. Se volevi lavorare su due branch contemporaneamente in due cartelle distinte, l’unica strada ufficiale era git clone ripetuto, con tutto lo spreco che comporta: spazio su disco duplicato, oggetti scaricati di nuovo, remote da riconfigurare e nessun collegamento tra le copie.

I worktree hanno spezzato quel vincolo. L’idea di fondo è elegante: lo storico di un repository (commit, branch, tag, oggetti) vive una volta sola dentro .git, mentre le working directory che lo materializzano su disco possono essere molte. Una sola fonte di verità, tante scrivanie di lavoro affacciate su di essa.

Un unico tronco (lo storico condiviso in .git) da cui si dirama una chioma di working directory indipendenti. I git worktree funzionano proprio così.

Il problema che risolvono davvero

Il modello classico di Git ha un collo di bottiglia preciso: la working directory è una sola, quindi può trovarsi su un solo branch alla volta. git checkout (o il più moderno git switch) è un’operazione distruttiva sul tuo spazio di lavoro: riscrive i file su disco per riflettere il branch di destinazione. Da qui discendono tutti i fastidi che conosci.

• Le modifiche non committate sono d’intralcio. Se hai file sporchi, Git si rifiuta di cambiare branch, o ti costringe a fare stash. Lo stash è una pila nascosta in cui è facilissimo dimenticare le cose.
• Cambiare branch invalida il lavoro di build. Cambi branch e i timestamp dei file cambiano: l’IDE reindicizza, il compilatore ricostruisce mezza soluzione, la cache dei test si svuota. In un progetto Delphi di una certa dimensione, o in qualunque codebase grande, questo significa minuti persi a ogni salto.
• Non puoi guardare due branch nello stesso momento. Vuoi confrontare il comportamento della feature con quello di main affiancati? Con una sola working directory non puoi: devi saltare avanti e indietro, ricostruendo ogni volta.

I worktree eliminano il collo di bottiglia alla radice. Ogni contesto di lavoro ottiene la sua cartella, con i suoi file, il suo stato di build, indipendente dalle altre. Cambiare contesto diventa un cd, non un git stash seguito da una ricostruzione.

Come si usano: i quattro comandi che servono

L’intera API dei worktree sta in una manciata di comandi. Partiamo dal presupposto di trovarti dentro un repository già clonato.

Creare un worktree su un branch esistente, in una cartella accanto a quella del progetto:

# Crea ../app-hotfix come working directory posizionata sul branch hotfix/login
git worktree add ../app-hotfix hotfix/login

Creare un worktree e un nuovo branch insieme, in un colpo solo:

# Crea il branch feature/export partendo da main e gli dedica una cartella
git worktree add -b feature/export ../app-export main

Elencare tutti i worktree attivi, con il path e il branch su cui si trovano:

git worktree list
# /home/daniele/app           a1b2c3d [main]
# /home/daniele/app-hotfix    e4f5g6h [hotfix/login]
# /home/daniele/app-export    i7j8k9l [feature/export]

Rimuovere un worktree quando hai finito, e fare pulizia dei riferimenti rimasti orfani:

git worktree remove ../app-hotfix
git worktree prune   # ripulisce i metadati di worktree cancellati a mano

Una nota che conviene tenere a mente fin da subito: Git non ti lascia fare checkout dello stesso branch in due worktree contemporaneamente. È una protezione voluta, non un limite arbitrario. Due cartelle che modificano lo stesso branch sarebbero una ricetta perfetta per confondersi e calpestarsi i commit a vicenda. Se ti serve davvero, esiste --force, ma nel 99% dei casi il messaggio di errore ti sta salvando da un guaio.

C’è anche qualche comando in più che usi più di rado ma che è bene sapere che esiste: git worktree move per spostare una working directory in un altro path, git worktree lock / unlock per impedire che un worktree (per esempio su un disco rimovibile o una share di rete) venga ripulito automaticamente, e git worktree repair per riparare i riferimenti quando hai spostato cartelle a mano e Git si è perso. Per l’uso quotidiano, però, i quattro comandi visti sopra coprono tutto.

E se preferisci il mouse alla tastiera, non sei tagliato fuori: i tool grafici più maturi espongono i worktree con la stessa naturalezza. In Git Extensions, per esempio, c’è un intero sottomenu dedicato sotto Repository, Worktrees, con le voci per crearne uno nuovo e per gestire quelli esistenti.

Creare e gestire i worktree da Git Extensions: nessuna riga di comando, solo un menu.

Un layout che si tiene in ordine da solo

Se i worktree diventano parte stabile del tuo flusso, un piccolo accorgimento di organizzazione li rende ancora più puliti. Invece di sparpagliare cartelle a casaccio sul disco, una convenzione molto diffusa è clonare il repository come bare dentro una cartella .bare, e tenere tutti i worktree come sottocartelle accanto ad essa, una per branch:

git clone --bare git@github.com:utente/app.git app/.bare
cd app
echo "gitdir: ./.bare" > .git
# checkout dei branch esistenti, ognuno nella sua cartella
git worktree add main main
git worktree add feature-export feature/export

Così il tuo progetto diventa una cartella app/ che contiene main/, feature-export/ e così via, ciascuna pronta all’uso, con lo storico condiviso nascosto in .bare. Nota che passo sempre il branch come secondo argomento: se lo ometti, Git usa solo l’ultimo segmento del path come nome del branch (da feature/export prenderebbe export) e finisce spesso per crearne uno nuovo, raramente quello che volevi. Non è un setup obbligatorio, ma quando lavori con molti worktree ti ringrazi da solo.

Esempi dalla vita reale

La teoria è breve, l’utilità è enorme. Ecco gli scenari in cui apro un worktree senza nemmeno pensarci.

L’hotfix mentre una feature è a metà

Torniamo alla scena dell’inizio. Sei a metà di feature/nuovo-report, working directory piena di modifiche. Arriva l’emergenza. Invece di fare stash:

git worktree add -b hotfix/crash-pdf ../app-hotfix main
cd ../app-hotfix
# qui sistemi il bug, committi, fai push, apri la PR
# nel frattempo la tua feature è rimasta intatta nell'altra cartella

Risolto l’incendio, fai cd di nuovo nella cartella della feature e ritrovi tutto esattamente come l’avevi lasciato: file aperti, stato di build, breakpoint. Zero stash, zero ricostruzioni.

La code review senza disturbare il proprio lavoro

Un collega ti chiede di rivedere la sua PR. Vuoi farla girare davvero, non solo leggere il diff su una pagina web. Con una sola working directory dovresti interrompere il tuo lavoro. Con un worktree, no:

git worktree add ../app-review feature/collega-pr
cd ../app-review
# compili, lanci, provi la feature del collega
# il tuo branch personale non viene nemmeno sfiorato

Build lunga in parallelo

Il caso classico dei progetti grandi: la build completa o la suite di test richiede minuti. Invece di restare con le mani in mano, lanci la build pesante in un worktree e continui a scrivere codice in un altro. Due cartelle, due stati di build indipendenti, nessuna interferenza.

Il confronto affiancato tra due versioni

Devi capire perché un comportamento è cambiato tra main e il branch di release? Apri due worktree, uno per ciascuno, e li metti letteralmente uno accanto all’altro in due finestre dell’editor. Niente salti avanti e indietro: li guardi nello stesso istante.

Perché gli agenti AI li usano tantissimo

Qui i worktree, da comodità personale, diventano abilitatori di un intero modo di lavorare. Gli agenti di coding basati su AI, come Claude Code e simili, hanno un appetito naturale per il lavoro parallelo: far girare più task contemporaneamente, ciascuno che modifica file, lancia build e committa in autonomia.

Il problema è che diverse istanze che lavorano nella stessa working directory si pesterebbero i piedi: un agente cambia un file mentre un altro lo sta compilando, i branch si sovrascrivono, lo stato diventa incoerente. La soluzione che questi strumenti adottano è proprio il git worktree: a ogni agente, o a ogni task parallelo, si assegna un worktree isolato. Ciascuno ha la sua cartella, il suo branch, il suo stato di build, ma tutti condividono lo stesso object database, quindi non c’è duplicazione dello storico e i risultati si reintegrano nel repository principale con un normale merge.

È esattamente lo stesso pattern che uso io a mano per l’hotfix, portato su scala industriale e automatizzato. Un agente lavora alla feature A in ../app-feature-a, un altro alla feature B in ../app-feature-b, un terzo sta facendo girare i test in ../app-tests, e nessuno dei tre sa nemmeno dell’esistenza degli altri. L’isolamento che rende i worktree comodi per noi è la stessa proprietà che li rende indispensabili per l’orchestrazione di più agenti in parallelo.

Qualche accortezza

I worktree sono solidi, ma un paio di cose conviene saperle prima di scottarsi.

• Stesso branch, un solo worktree. Lo abbiamo detto: è una protezione, non un difetto. Per provare lo stesso branch in due posti, crea un branch di appoggio.
• La configurazione è condivisa, la working directory no. I worktree condividono config, gli oggetti e i branch, ma ciascuno ha il proprio HEAD, il proprio index e i propri file. Lo stash, attenzione, è condiviso a livello di repository: non legarlo a un worktree specifico nella tua testa.
• Fai pulizia. Quando cancelli una cartella di worktree a mano invece che con git worktree remove, restano dei metadati orfani: git worktree prune li ripulisce. git worktree list è il tuo cruscotto per non perdere il conto.
• I submodule richiedono attenzione. Se il progetto usa submodule, ricordati di inizializzarli anche nel nuovo worktree; non vengono materializzati da soli.

Punti chiave

• Un repository, tante working directory. I git worktree, introdotti in Git 2.5 (luglio 2015), ti danno più cartelle di lavoro dallo stesso .git, ciascuna su un branch diverso.
• Cambiare contesto diventa un cd. Niente più git stash né riclonazioni per gestire un hotfix urgente: apri un worktree, lavori, lo chiudi, e il lavoro originale resta intatto.
• Lo stato di build sopravvive. Ogni worktree mantiene la propria indicizzazione e cache di compilazione: cambiare contesto non costringe l’IDE a ricominciare da capo.
• Pochi comandi. git worktree add, git worktree list, git worktree remove, git worktree prune: è praticamente tutto qui.
• Sono il motore del lavoro parallelo degli agenti AI. Assegnare un worktree isolato a ogni agente o task è il pattern che permette a più agenti di lavorare sullo stesso repository senza calpestarsi.
• Una protezione da ricordare. Lo stesso branch non può stare in due worktree contemporaneamente: è voluto, ed è un bene.

Domande frequenti

In quale versione di Git sono arrivati i worktree?

Il comando git worktree è stato introdotto in Git 2.5, rilasciato il 27 luglio 2015. Da allora è una funzionalità stabile e disponibile in qualunque installazione moderna di Git.

Che differenza c’è tra git worktree e clonare di nuovo il repository?

Una nuova clonazione crea una copia completamente separata: object database duplicato, spazio su disco doppio, remote da riconfigurare e nessun collegamento con l’originale. Un worktree, invece, aggiunge solo una working directory: lo storico, i branch e gli oggetti restano condivisi in un unico .git. È molto più leggero e i branch creati in un worktree sono immediatamente visibili agli altri.

Posso fare checkout dello stesso branch in due worktree?

No, e di proposito. Git impedisce di posizionare lo stesso branch in due worktree contemporaneamente per evitare che due cartelle ne riscrivano lo stato in modo incoerente. Se ti serve davvero, puoi forzare con --force, ma quasi sempre la soluzione corretta è creare un branch di appoggio.

Perché gli agenti di coding AI usano i worktree?

Perché abilitano il lavoro parallelo senza conflitti. Assegnando a ogni agente o task un worktree isolato, più agenti possono modificare file, compilare e committare contemporaneamente sullo stesso repository senza pestarsi i piedi, condividendo comunque un unico storico in cui reintegrare i risultati.

Come rimuovo un worktree quando ho finito?

Usa git worktree remove <path> per eliminarlo in modo pulito. Se invece hai cancellato la cartella a mano, lancia git worktree prune per ripulire i metadati rimasti orfani. Con git worktree list controlli in qualsiasi momento quali worktree sono attivi.