Tutorial su Git Worktree: lavora su più branch senza cambiare

Stai lavorando su un feature branch quando un collega ti chiede di rivedere la sua pull request. Potresti fare stash delle modifiche, cambiare branch e sperare di ricordarti dove eri rimasto. Oppure potresti fare commit di lavoro a metà solo per non perderlo. Poi arriva l’hotfix d’emergenza: la produzione è giù e tu sei immerso in un refactoring che tocca metà del codebase. Ogni cambio di contesto come questo costa 10–15 minuti di setup e interrompe la concentrazione.

Git worktree risolve il problema permettendoti di fare checkout di più branch contemporaneamente in directory separate. Invece di fare stash o commit di lavoro incompleto, ti basta cd in un’altra directory dove è già stato fatto il checkout di un altro branch. Lavori sull’hotfix, lo deployi, poi fai cd di nuovo sul tuo feature esattamente com’era.

In questo tutorial, ti mostrerò come creare e gestire worktree, evitare gli errori più comuni e integrarli nel tuo flusso di lavoro quotidiano. Dovresti già conoscere i branch Git, i commit e le operazioni di base da riga di comando. Se prima vuoi ripassare le basi di Git, ti consiglio il tutorial Introduzione a Git di DataCamp per coprire gli elementi essenziali.

Che cos’è Git Worktree?

Git worktree è una funzionalità integrata che crea directory di lavoro aggiuntive collegate allo stesso repository. La tua directory di lavoro principale è la worktree primaria e ogni worktree aggiuntiva che crei ottiene la sua directory con il suo branch in checkout. Tutte queste worktree si collegano allo stesso repository .git.

Questa architettura con repository condiviso significa che i commit che fai in qualsiasi worktree compaiono immediatamente nel database Git condiviso, accessibili da tutte le altre worktree. I file rimangono indipendenti — modificare train.py in una worktree influisce solo su quella directory finché non fai commit delle modifiche.

Perché non usare semplicemente terminal diversi?

Non puoi aprire più terminal nella stessa directory e lavorare su branch diversi contemporaneamente. Git permette un solo branch in checkout per directory. Quando esegui git checkout feature-b in un terminale, cambia i file per ogni terminale che punta a quella directory.

Git worktree lo risolve dando a ogni branch la sua directory. Ogni directory è completamente indipendente, con i propri file, processi in esecuzione e artefatti di build. Passare tra branch diventa cd ../different-directory invece di git checkout different-branch.

Prerequisiti per Git Worktree

Prima di usare git worktree, verifica la tua configurazione:

• Git 2.5 o successivo: esegui git --version per controllare. Git worktree è stato rilasciato nel 2015, quindi la maggior parte delle installazioni lo include
• Repository Git esistente: ti serve un repository con almeno un branch
• Familiarità con la riga di comando: tutte le operazioni su worktree avvengono nel terminale

Controlla che worktree sia disponibile:

git worktree --help

Se viene mostrata la pagina di help, sei pronto.

Quando usare git worktree

Git worktree funziona bene quando cambiare branch interromperebbe il lavoro in corso:

• Code review: testa le modifiche di un collega senza fare stash del tuo feature work
• Hotfix d’emergenza: correggi bug in produzione mantenendo intatto il tuo refactoring
• Sviluppo in parallelo: lavora su due feature indipendenti senza cambiare branch continuamente
• Processi lunghi: avvia una suite di test da 30 minuti e continua a scrivere codice in un’altra worktree

Evitalo per attività rapide sotto i 10 minuti in cui git checkout è più semplice, o quando sei concentrato su un unico lavoro senza interruzioni previste.

Creare la tua prima Worktree

Il modo migliore per capire git worktree è crearne una e vederla in azione. Vedremo i comandi di base, esploreremo la struttura creata da Git e osserveremo come fluiscono le modifiche tra le worktree.

Configurare un repository di esempio

Prima di immergerti nelle worktree, ti serve un repository Git su cui lavorare. Se hai già un progetto Python con più branch, passa alla sezione successiva. Altrimenti, configuriamo velocemente una semplice pipeline ML:

mkdir ml-pipeline
cd ml-pipeline
git init

Crea un README e uno script Python:

echo "# ML Pipeline" > README.md
echo "def load_data():" > train.py
echo "    print('Loading training data...')" >> train.py

Verifica che i file siano stati creati:

ls
# You should see: README.md  train.py

Fai commit di questi file e crea un feature branch:

git add .
git commit -m "Initial commit"
git branch feature-preprocessing

Ora hai un repository con due branch: main (il tuo branch corrente) e feature-preprocessing.

Creazione base di una worktree

Creare una worktree per un branch esistente richiede un solo comando. Facciamo il checkout di feature-preprocessing in una directory separata:

git worktree add ../ml-pipeline-preprocessing feature-preprocessing

Questo crea una nuova directory chiamata ml-pipeline-preprocessing un livello sopra la tua posizione attuale, fa il checkout del branch feature-preprocessing lì e la collega al repository esistente.

Git conferma la creazione:

Preparing worktree (checking out 'feature-preprocessing')
HEAD is now at 0a7f986 Initial commit

Per lavoro del tutto nuovo, crea insieme branch e worktree:

git worktree add -b feature-visualization ../ml-pipeline-viz

Il flag -b crea un nuovo branch chiamato feature-visualization e lo mette in checkout nella nuova worktree.

Esplorare la struttura delle worktree

Con la worktree creata, ora hai più directory sul filesystem. Per vederle tutte:

git worktree list

/Users/you/projects/ml-pipeline                  0a7f986 [main]
/Users/you/projects/ml-pipeline-preprocessing    0a7f986 [feature-preprocessing]

La prima riga mostra la tua worktree principale — la directory originale che contiene la cartella .git. La seconda riga mostra la worktree collegata. Entrambe visualizzano l’hash del commit corrente e il branch in checkout.

Ogni directory di worktree funziona come un repository Git completo. Puoi entrarci, modificare file, eseguire git status e fare commit. Le worktree collegate non contengono un’intera directory .git—hanno invece un file .git che punta al repository principale. All’interno della directory .git principale, una cartella worktrees archivia i metadati di ogni worktree collegata.

Lavorare in una worktree

Vai nella worktree feature-preprocessing e fai un commit:

cd ../ml-pipeline-preprocessing
cat >> train.py << 'EOF'

def preprocess_features(df):
   """Normalize numeric features."""
   return (df - df.mean()) / df.std()
EOF
git add train.py
git commit -m "Add feature preprocessing function"

Il commit va a buon fine normalmente:

[feature-preprocessing 7c8d4e2] Add feature preprocessing function
1 file changed, 3 insertions(+)

Torna alla worktree principale e controlla la cronologia dei commit:

cd ../ml-pipeline
git log --oneline --all

Il tuo nuovo commit compare:

7c8d4e2 Add feature preprocessing function
0a7f986 Initial commit

Nota come il commit appare immediatamente in entrambe le posizioni senza comandi aggiuntivi.

Casi d’uso di Git Worktree

Ora che sai come creare e lavorare con le worktree, vediamo scenari pratici in cui risolvono problemi reali di sviluppo.

Workflow di code review

Un collega ha bisogno di feedback sulla sua PR. Invece di fare stash delle modifiche e cambiare branch, crea una directory separata per la review:

git worktree add ../ml-pipeline-review pr/update-training
cd ../ml-pipeline-review
pip install -r requirements.txt
python train_model.py --config experiments/baseline.yaml

Testa le modifiche e lascia il tuo feedback. Quando hai finito:

cd ../ml-pipeline
git worktree remove ../ml-pipeline-review

Il tuo lavoro originale rimane intatto. Niente stash e nessun cambio di contesto necessario. Per altre strategie su code review efficaci, dai un’occhiata alla guida alle best practice per le code review di DataCamp.

Hotfix d’emergenza

Senza worktree:

• Salva da qualche parte le modifiche del refactoring (stash o commit WIP)
• Fai checkout del branch main
• Correggi il bug
• Fai push in produzione
• Fai checkout del feature branch
• Ripristina le modifiche (unstash o revert del commit WIP)
• Ricostruisci il contesto mentale di ciò che stavi facendo

Con le worktree:

git worktree add ../ml-pipeline-hotfix main
cd ../ml-pipeline-hotfix

Correggi e deploya:

git add src/data/validation.py
git commit -m "Fix schema validation for nullable timestamp fields"
git push origin main
cd ../ml-pipeline
git worktree remove ../ml-pipeline-hotfix

In pochi secondi sei di nuovo sul tuo refactoring, con tutti i file esattamente com’erano.

Sviluppo di feature in parallelo

Stai implementando metriche personalizzate e un nuovo data loader — due feature indipendenti. Imposta una worktree per ciascuna:

git worktree add -b feature-custom-metrics ../ml-pipeline-metrics
git worktree add -b feature-streaming-loader ../ml-pipeline-loader

Il tuo filesystem ora appare così:

~/projects/
 ml-pipeline/           [main] - your usual work
 ml-pipeline-metrics/   [feature-custom-metrics]
 ml-pipeline-loader/    [feature-streaming-loader]

Esegui entrambe le feature in parallelo — ognuna nel suo terminale:

# Terminal 1
cd ~/projects/ml-pipeline-metrics
python experiments/evaluate_custom_metrics.py

# Terminal 2 
cd ~/projects/ml-pipeline-loader
pytest tests/test_data_loader.py -v

Entrambi i processi vengono eseguiti in contemporanea senza conflitti. Quando una feature è completa, fai merge e rimuovi la worktree:

cd ~/projects/ml-pipeline
git merge feature-custom-metrics
git worktree remove ../ml-pipeline-metrics

Gestire e ripulire le worktree

Elencare le worktree

Per vedere tutte le worktree in un repository:

git worktree list

/Users/you/projects/ml-pipeline                  a3f9c81 [main]
/Users/you/projects/ml-pipeline-review           b7d4e92 [pr/data-validation]
/Users/you/projects/ml-pipeline-hotfix           a3f9c81 [hotfix/schema-bug]

Ogni riga mostra il percorso della directory, l’hash del commit corrente e il branch in checkout. La prima voce è sempre la tua worktree principale (che contiene la cartella .git), le restanti sono worktree collegate.

Per scripting o navigazione rapida, estrai solo i percorsi:

git worktree list | awk '{print $1}'

Rimuovere le worktree

Quando finisci di lavorare in una worktree, rimuovila correttamente:

cd ~/projects/ml-pipeline
git worktree remove ../ml-pipeline-review

Git protegge dalla perdita di dati. Se hai modifiche non committate:

git worktree remove ../ml-pipeline-review

fatal: '../ml-pipeline-review' contains modified or untracked files, use --force to delete it

Forza la rimozione se sei sicuro:

git worktree remove --force ../ml-pipeline-review

Se una worktree è bloccata, usa --force due volte:

git worktree remove --force --force ../ml-pipeline-locked

Se hai eliminato manualmente una directory di worktree (rm -rf o file manager), Git la traccia ancora internamente. Ripulisci i riferimenti obsoleti:

git worktree prune

Anteprima di ciò che verrebbe rimosso:

git worktree prune --dry-run

Best practice ed errori comuni

Vediamo alcuni modi per ottenere il massimo dalle worktree e come evitare errori comuni. 

Organizzazione delle worktree

Dove metti le worktree è importante. La maggior parte degli sviluppatori le posiziona come directory sorelle del repository principale:

~/projects/
 ml-pipeline/                    # main worktree
 ml-pipeline-feature-auth/       # linked worktree
 ml-pipeline-hotfix-login/       # linked worktree

Questa struttura mantiene tutto in un unico posto e rende i percorsi prevedibili. Il pattern projectname-branchname ti dice esattamente cosa contiene ogni directory.

Alcuni preferiscono una cartella dedicata:

~/projects/
 ml-pipeline/                    # main worktree
 ml-pipeline-worktrees/
   feature-auth/
   hotfix-login/

Scegli un approccio e usalo con coerenza. Nomi descrittivi come ml-pipeline-user-authentication rendono le directory autoesplicative, mentre nomi generici come ml-pipeline-temp o ml-pipeline-2 ti costringono a controllare cosa c’è dentro. Considera le worktree come temporanee—creale per un compito specifico, poi rimuovile quando hai finito.

Errori comuni

Stesso branch in più worktree

Git impedisce di mettere in checkout lo stesso branch in due worktree:

git worktree add ../ml-pipeline-duplicate main

fatal: 'main' is already used by worktree at '/Users/you/projects/ml-pipeline'

Questa protezione esiste perché potresti creare commit in conflitto. Se ti serve lo stesso codice in due posti, crea un nuovo branch.

Worktree dimenticate e spazio su disco

Ogni worktree rimane nel filesystem finché non la rimuovi esplicitamente. Le worktree vecchie si accumulano; i progetti possono raccoglierne 15+ dimenticate, consumando gigabyte.

Ogni worktree contiene una copia completa dei file del repository. Un repository da 500MB con 5 worktree consuma 2,5GB. Rimuovi le worktree quando hai finito:

git worktree list
git worktree remove ../ml-pipeline-old-feature

Nidificare worktree

Non creare una worktree all’interno della directory di un’altra worktree. Git lo permette, ma crea strutture di directory confuse e rende la pulizia soggetta a errori.

Ottimizzazione del workflow

Alias della shell fanno risparmiare tempo se crei spesso worktree:

alias gwl='git worktree list'
alias gwa='git worktree add'
alias gwr='git worktree remove'

Per setup più complessi, scrivi una funzione che crea una worktree e configura l’ambiente di sviluppo in un solo passaggio:

wt() {
 git worktree add "../${PWD##*/}-$1" -b "$1"
 cd "../${PWD##*/}-$1"
 python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt
}

La variabile ${PWD##*/} estrae il nome della directory corrente. Eseguire wt feature-logging da ml-pipeline crea ml-pipeline-feature-logging, ci entra e imposta un ambiente virtuale Python con le dipendenze.

Creare una worktree diventa un solo comando:

wt feature-custom-metrics

Adattalo al tuo linguaggio: sostituisci il setup Python con bundle install per Ruby, cargo build per Rust o npm install per Node.js.

Il tuo editor o IDE funziona con le worktree senza configurazioni speciali. Ogni worktree è solo una directory, quindi aprila come qualsiasi altra cartella di progetto. La maggior parte degli editor moderni supporta l’apertura di più root di progetto contemporaneamente — puoi avere tre worktree aperte in una finestra e passare tra loro dalla sidebar.

Worktree avanzate: sviluppo parallelo assistito dall’AI

Se usi assistenti di coding AI, le worktree sbloccano un potente flusso di lavoro in parallelo. Questo approccio ha preso piede tra sviluppatori e team nel 2024–2025.

Crea worktree separate per compiti differenti:

git worktree add -b feature-add-logging ../ml-pipeline-logging
git worktree add -b feature-optimize-preprocessing ../ml-pipeline-optim
git worktree add -b bugfix-memory-leak ../ml-pipeline-bugfix

Apri un pannello di terminale per ogni worktree e avvia il tuo assistente AI:

# Pane 1
cd ~/projects/ml-pipeline-logging
claude

# Pane 2
cd ~/projects/ml-pipeline-optim
claude

# Pane 3
cd ~/projects/ml-pipeline-bugfix
claude

Ogni istanza AI lavora su una feature diversa senza interferenze. I team riportano di completare lavoro in ore che prima richiedevano giorni. Ad esempio, incident.io esegue 4–5 agenti Claude Code in parallelo usando questo schema. In un caso, Claude ha stimato che un miglioramento UI avrebbe richiesto 2 ore ma ha finito in 10 minuti.

Compromessi da considerare:

• Consumo di token: più sessioni AI usano più crediti API e possono raggiungere i rate limit
• Overhead di setup: ogni worktree ha bisogno del proprio ambiente virtuale e dipendenze
• Carico cognitivo: gestire più conversazioni su compiti differenti

Funziona bene per feature grandi e indipendenti (30+ minuti ciascuna) dove il lavoro non tocca gli stessi file e hai sufficiente quota API. Evitalo per bugfix rapidi, feature strettamente accoppiate o quando sei vicino ai rate limit API.

Conclusione

Ricordi lo scenario iniziale — un collega ha bisogno di una PR review mentre sei a metà di una feature. Ora conosci la soluzione: git worktree add ../ml-pipeline-review pr/branch-name, poi cd per iniziare a rivedere. Il tuo lavoro sulla feature resta intatto. Niente stash, niente commit di codice a metà, niente sforzo mentale per ricostruire il contesto quando torni. Due directory, due branch, zero attrito.

Git worktree non aggiunge complessità al tuo flusso di lavoro — la rimuove. Ogni worktree è solo una directory con un branch in checkout. Ma questa semplicità sblocca qualcosa di potente: la possibilità di cambiare contesto all’istante tra i task senza il carico cognitivo di fare stash, checkout e ricostruire il modello mentale. 

Quando ti serve integrare le worktree con i flussi di collaborazione del team come pull request e code review, il percorso di competenze GitHub Foundations di DataCamp copre le pratiche essenziali per lavorare in modo efficace con team distribuiti.