modulo 07 / lezione 33

Casi reali, debugging della storia, recupero

git worktree: più branch in cartelle separate

Lavorare su più branch contemporaneamente senza switchare e perdere stato del working tree.

60 minGit e controllo versione

git worktree: più branch in cartelle separate

git worktree permette di avere più cartelle di lavoro collegate allo stesso repository. Ogni worktree ha working tree e index separati, ma condivide la storia Git e gli oggetti del repo principale.

Il vantaggio pratico è semplice: puoi lavorare su una feature, aprire un hotfix urgente in un’altra cartella e tornare alla feature senza stash continui o switch rischiosi.

Perché questa lezione conta

git switch è sufficiente finché hai un solo contesto attivo. Diventa scomodo quando devi:

  1. correggere un bug urgente mentre hai modifiche non pronte;
  2. confrontare due branch in editor diversi;
  3. eseguire due versioni dell’app in parallelo;
  4. fare review locale di una PR senza sporcare il lavoro corrente.

worktree rende questi scenari espliciti e ordinati.

Obiettivo operativo

Alla fine della lezione devi saper creare worktree su branch esistenti o nuovi, elencarli, rimuoverli, capire i limiti sui branch già checkoutati e scegliere quando usarli al posto di stash o cloni separati.

Creare un worktree

Da dentro il repository principale:

git worktree add ../progetto-hotfix hotfix/login-timeout

Se il branch non esiste:

git worktree add -b hotfix/login-timeout ../progetto-hotfix origin/main

Poi:

cd ../progetto-hotfix
git status -sb

Ora quella cartella è un checkout separato. Puoi installare dipendenze, avviare server, fare commit e push da lì.

Vedere e rimuovere worktree

git worktree list

Output tipico:

/repo/progetto          abc1234 [feat/profilo]
/repo/progetto-hotfix   def4567 [hotfix/login-timeout]

Quando hai finito:

git worktree remove ../progetto-hotfix
git worktree prune

prune pulisce riferimenti a worktree rimossi manualmente o non più disponibili.

Limite importante

Lo stesso branch non può essere checkoutato in due worktree contemporaneamente. Se feat/profilo è già aperto nella cartella principale, Git ti impedirà di aggiungerlo in un’altra cartella.

Soluzioni:

  1. usa un branch diverso;
  2. crea un branch temporaneo;
  3. fai checkout detached di uno SHA se devi solo ispezionare;
  4. chiudi o rimuovi il worktree precedente.

Questo vincolo protegge dal modificare lo stesso branch da due posti diversi.

Worktree vs stash vs clone

stash è utile per mettere via modifiche per poco tempo, ma diventa fragile se lo usi come magazzino di contesti.

Un secondo clone funziona, ma duplica oggetti Git e configurazione.

worktree è il compromesso: cartelle separate, repository condiviso, meno spreco e più chiarezza.

Caso reale: hotfix

Se stai lavorando su feat/checkout e arriva un bug urgente:

git status -sb
git worktree add -b hotfix/payment-timeout ../app-hotfix origin/main
cd ../app-hotfix
npm install
# fix, test, commit, push, PR

La feature resta intatta nella cartella originale. Non devi nascondere modifiche non pronte.

Attenzioni pratiche

Ogni worktree può avere file generati, dipendenze e .env propri. In progetti Node potresti dover installare dipendenze in ogni cartella, a meno che il setup non supporti cache o workspace condivisi.

Non cancellare cartelle worktree a caso. Preferisci git worktree remove, così Git aggiorna i metadati correttamente.

Laboratorio guidato

Su un repo demo:

  1. crea branch feat/profilo e lascia una modifica non committata;
  2. crea un worktree ../repo-hotfix da origin/main;
  3. fai un commit hotfix nel worktree;
  4. pushalo su remoto o simula il push;
  5. rimuovi il worktree;
  6. torna alla cartella originale e verifica che il lavoro feature sia rimasto intatto.

Output atteso

Un playbook:

Uso worktree quando ho due contesti Git veri.
Uso stash solo per interruzioni brevi.
Creo worktree fuori dalla cartella repo.
Rimuovo con git worktree remove.
Controllo sempre git worktree list.

Errori comuni

Usare worktree come cartelle permanenti dimenticate. Diventano rumore operativo.

Cancellare la cartella senza remove. Poi serve git worktree prune.

Provare lo stesso branch in due worktree. Git lo blocca per una buona ragione.

Confondere worktree con submodule. Worktree è lo stesso repo in più cartelle; submodule è un altro repo dentro il repo.

Checklist di verifica

  • so creare worktree su branch nuovo;
  • so elencare e rimuovere worktree;
  • so spiegare perché un branch non può stare in due worktree;
  • so scegliere tra stash, worktree e clone;
  • so usare worktree per hotfix senza interrompere feature in corso.

Esercizi

Base · facile

Crea un secondo worktree per lavorare su un branch diverso in una cartella separata.

Soluzione 
git worktree add ../repo-hotfix hotfix/urgente
# ora ../repo-hotfix è una cartella sul branch hotfix/urgente,
# collegata allo stesso repository

git worktree add crea una cartella di lavoro aggiuntiva legata allo stesso repo, ciascuna su un branch diverso. Puoi avere più branch “aperti” contemporaneamente senza fare switch.

Intermedio · medio

Elenca i worktree e rimuovine uno quando hai finito. Spiega il vantaggio rispetto a git stash + switch.

Soluzione 
git worktree list
git worktree remove ../repo-hotfix

Con stash+switch interrompi il lavoro corrente, cambi branch e poi torni: un solo working tree alla volta. Con i worktree il lavoro in corso resta intatto nella sua cartella mentre gestisci l’urgenza in un’altra: niente stash, niente ricompilazioni dovute al cambio branch, e puoi persino tenere due build attive in parallelo.

Sfida · difficile

Spiega i vincoli dei worktree (lo stesso branch non può essere su due worktree) e un flusso reale in cui i worktree brillano.

Soluzione 
git worktree add ../rec review/pr-123   # cartella dedicata per revisionare una PR
# build/test della PR girano qui senza toccare il tuo lavoro principale
git worktree remove ../rec

Vincolo: lo stesso branch non può essere fatto checkout in due worktree insieme (Git lo blocca per evitare stati incoerenti). Flusso ideale: stai sviluppando una feature con una build lunga in corso e arriva una PR da revisionare o un hotfix urgente — apri un worktree dedicato, lo gestisci e lo rimuovi, senza interrompere né ricompilare il tuo ambiente principale.

Collegamenti

  • Modulo: Casi reali, debugging della storia, recupero - lezione 33 del corso.
  • Si collega a branch, stash e workflow di team.