git worktree

Cosa fa git worktree

Il comando git worktree ti permette di fare il checkout di più branch contemporaneamente da un singolo repository. Ogni worktree è una directory di lavoro separata con il proprio branch estratto e il proprio indice, ma condividono tutti lo stesso archivio di oggetti .git, la cronologia, i ref e la configurazione. È il modo pulito per lavorare su due branch in parallelo senza clonare il repository due volte.

La directory in cui hai clonato è il tuo main worktree; ogni directory che crei con git worktree add è un linked worktree. I linked worktree sono economici: memorizzano solo un piccolo file .git (non una cartella) che punta al repository condiviso, quindi costano quasi nulla su disco rispetto a un secondo clone.

Questa pagina spiega quando usare un worktree, come aggiungere, elencare, spostare e rimuovere worktree, le regole che Git impone e gli errori comuni da evitare.

Il problema che risolve

Immagina di essere immerso in un feature branch quando arriva una segnalazione di bug urgente. Di solito dovresti fare lo stash del tuo lavoro, cambiare branch, correggere il bug, tornare indietro e ripristinare lo stash — un processo fastidioso e soggetto a errori. Con i worktree, crei semplicemente una seconda directory di lavoro estratta sul branch di hotfix, correggi il bug lì e lasci il tuo lavoro sul feature branch completamente intatto. Quando la build richiede i due stati affiancati — per esempio per confrontare il comportamento o eseguire due lunghe suite di test contemporaneamente — i worktree eccellono dove il semplice stash non può aiutare.

Aggiungere un worktree

Indica a git worktree add un percorso e un branch. Per fare il checkout di un branch esistente in una directory adiacente:

git worktree add ../hotfix hotfix

Questo crea ../hotfix con il branch hotfix estratto:

Preparing worktree (checking out 'hotfix')
HEAD is now at 1a2b3c4 Add login form

Per creare un nuovo branch allo stesso tempo, usa -b. L'ultimo argomento è il punto di partenza su cui si basa il nuovo branch:

git worktree add -b experiment ../experiment main

Ora hai due directory di lavoro indipendenti supportate da un unico repository. Se ometti completamente il branch, Git crea un branch con il nome dell'ultimo componente del percorso:

git worktree add ../docs    # creates and checks out a branch named "docs"

Per ispezionare un commit senza posizionare un branch lì — utile per testare una vecchia release — aggiungilo in stato detached HEAD:

git worktree add --detach ../v1-check v1.0.0

Consulta Detached HEAD per capire cosa significa quello stato.

Elencare i worktree

Visualizza ogni albero di lavoro collegato al repository:

git worktree list

L'output mostra ogni percorso, il commit su cui si trova e il branch (oppure (detached HEAD)):

/home/dev/project          1a2b3c4 [main]
/home/dev/hotfix           9f8e7d6 [hotfix]
/home/dev/v1-check         0011223 (detached HEAD)

Aggiungi --porcelain per un formato stabile e adatto agli script.

Spostare e rimuovere worktree

Per spostare un linked worktree, lascia che Git aggiorni la sua contabilità al posto tuo invece di usare il comando shell mv:

git worktree move ../hotfix ../urgent-fix

Quando hai finito con uno, rimuovilo (questo elimina la sua directory):

git worktree remove ../urgent-fix

Git si rifiuta di rimuovere un worktree che ha modifiche non committate o file non tracciati, quindi non perdi lavoro per errore. Una volta che sei sicuro, ignora questo controllo con --force:

git worktree remove --force ../urgent-fix

Se hai eliminato manualmente la cartella di un worktree con rm -rf, il repository conserva ancora un record amministrativo obsoleto. Ripuliscilo con:

git worktree prune

Bloccare un worktree

Se un worktree si trova su un disco rimovibile o una condivisione di rete, bloccalo in modo che prune non rimuova mai la sua contabilità mentre il disco è smontato:

git worktree lock ../usb-backup --reason "external disk"
git worktree unlock ../usb-backup

Riepilogo dei comandi

Regole e avvertenze

• Un branch, un worktree. Un branch può essere estratto in un solo worktree alla volta. Se provi ad aggiungere un worktree per un branch già estratto altrove, Git si rifiuta con fatal: '<branch>' is already used by worktree at .... Questo garantisce che due directory non possano mai competere sullo stesso puntatore di branch. Usa --detach, o un nuovo branch con -b, se hai bisogno dello stesso commit in due posti.
• Le modifiche locali non sono condivise. Ogni worktree ha i propri file di lavoro, indice e stash. I commit, i branch, i tag e i remote sono condivisi perché risiedono nel deposito .git comune.
• Rimozione del main worktree. Non puoi eseguire git worktree remove sul worktree originale (main) — solo su quelli collegati.
• I repository bare sono un ottimo host per i worktree: clona con git clone --bare, poi aggiungi ogni branch di lavoro come proprio worktree, mantenendo i dati del repository separati da qualsiasi checkout.

Comandi correlati

• git branch — crea e gestisce i branch che estrai nei worktree.
• git switch — passa tra i branch all'interno di una singola directory di lavoro.
• git stash — l'alternativa più vecchia, a directory singola, a un worktree rapido.

Esercitazione