git checkout

Cosa fa git checkout

git checkout è uno dei comandi più versatili di Git. Svolge due funzioni distinte:

1. Cambiare branch — sposta HEAD per puntare a un altro branch e aggiorna i file nella directory di lavoro in modo che corrispondano all'ultimo commit di quel branch.
2. Ripristinare file — sovrascrive i file nella directory di lavoro (o nell'area di staging) con una versione proveniente da un commit, da un branch o dall'indice.

HEAD è il puntatore di Git che indica "dove ti trovi ora" — normalmente la punta del branch che hai estratto. Quando esegui git checkout, Git sposta HEAD e riscrive i file tracciati in modo che l'albero di lavoro rispecchi la destinazione.

Poiché il comando è sovraccarico di funzioni, il Git moderno (2.23+) ha suddiviso i suoi due ruoli in due comandi più chiari: git switch per spostarsi tra i branch e git restore per annullare le modifiche ai file. git checkout funziona esattamente come prima ed è illustrato in questa pagina, con gli equivalenti moderni indicati dove utile.

Questa pagina tratta il checkout di branch esistenti e nuovi, il lavoro con branch remoti, il ripristino di file e lo stato "detached HEAD".

Passare a un branch esistente

Se un repository contiene già diversi branch, git checkout <branch> consente di passare a uno di essi. Esegui prima git branch per elencare i branch disponibili; il branch corrente è contrassegnato con un asterisco:

Elencare i branch e passare a uno di essi

$ git branch
* master
  test_branch
  feature_branch

$ git checkout feature_branch
Switched to branch 'feature_branch'

Dopo il cambio, la directory di lavoro corrisponde all'ultimo commit su feature_branch, e tutti i nuovi commit che crei vengono registrati lì. L'equivalente moderno è git switch feature_branch.

Git rifiuta di cambiare branch se hai modifiche non committed che verrebbero sovrascritte dal branch di destinazione. In tal caso, esegui il commit, mettile in stash o eliminale prima.

Creare e passare a un nuovo branch

Per creare un branch e passarci in un unico passaggio, usa il flag -b:

git checkout -b

git checkout -b new_branch

Il flag -b dice a Git di eseguire git branch new_branch (crea il branch dall'attuale HEAD) e poi immediatamente git checkout new_branch. È equivalente a:

git branch new_branch
git checkout new_branch

Per impostazione predefinita, il nuovo branch parte dall'attuale HEAD. Per basarlo su un branch o un commit diverso, indica un punto di partenza:

git checkout -b da un punto di partenza specifico

git checkout -b new_branch existing_branch

In questo caso new_branch viene creato alla punta di existing_branch anziché all'attuale HEAD. L'equivalente moderno è git switch -c new_branch existing_branch.

Cambiare branch e HEAD

Eseguire git checkout <branch> punta HEAD alla punta di quel branch:

git checkout main

Se cambi branch per errore o perdi traccia di dove si trovava HEAD, il comando git reflog elenca ogni posizione che HEAD ha occupato, così puoi tornare a uno stato precedente.

Passare a un branch remoto

Quando lavori in team, il repository remoto contiene branch inviati da altre persone. Per vederli e passarci, scarica prima i dati remoti più recenti con git fetch:

git fetch --all

Il Git moderno può quindi eseguire il checkout di un branch remoto tramite il suo nome breve. Git crea automaticamente un branch locale che traccia il branch remoto corrispondente:

git checkout feature_branch

Questo funziona solo quando esattamente un remote ha un branch con quel nome. Se il nome è ambiguo, o vuoi essere esplicito, crea un branch locale di tracciamento dalla ref di tracciamento remota:

Creare un branch locale da uno remoto

git checkout -b feature_branch origin/feature_branch

Il flag -b è necessario qui — il nuovo branch locale feature_branch viene creato a partire da, e impostato per tracciare, origin/feature_branch. Per forzare un branch locale esistente a corrispondere esattamente alla punta del remote, usa git reset:

git reset --hard origin/feature_branch

git reset --hard elimina i commit locali e le modifiche non committed su quel branch, quindi usalo solo quando intendi scartare il lavoro locale.

Ripristinare file con git checkout

Oltre a cambiare branch, git checkout può sostituire i file nell'albero di lavoro con una versione dall'indice o da un altro commit.

Annulla le modifiche non committed in un singolo file e ripristina la versione dell'ultimo commit:

Annullare le modifiche in un file

git checkout -- file.txt

Il -- separa le opzioni del comando dal percorso del file, evitando ambiguità quando un file e un branch hanno lo stesso nome. L'equivalente moderno è git restore file.txt.

Ripristina un file così come esisteva in un commit o branch specifico, senza cambiare branch:

Ripristinare un file da un altro commit

git checkout <commit> -- file.txt

Questo aggiorna file.txt nella directory di lavoro e nell'area di staging con il suo contenuto in <commit>, mentre HEAD rimane sul branch corrente. Vedi git restore per la sintassi moderna più chiara.

Stato detached HEAD

Il checkout di un commit specifico (anziché di un branch) ti mette nello stato detached HEAD:

git checkout a1b2c3d

Normalmente HEAD punta a un branch, che a sua volta punta a un commit. Quando esegui il checkout di un commit direttamente, HEAD punta direttamente a quel commit senza alcun branch collegato — questo è ciò che significa "detached". È utile per esaminare o testare uno stato precedente del progetto.

Il rischio è che qualsiasi commit effettuato in questo stato non si trova su un branch. Non appena si passa a un altro branch, quei commit non hanno alcun riferimento che li punti e diventano difficili da trovare (Git alla fine li raccoglierà come spazzatura). Se decidi di mantenere il lavoro fatto in uno stato detached HEAD, crea un branch prima di uscire:

git switch -c new_branch

In sintesi: esaminare un vecchio commit in un detached HEAD è perfettamente sicuro, ma effettua qualsiasi nuovo sviluppo su un branch reale in modo che i tuoi commit rimangano raggiungibili. Il git reflog può comunque aiutarti a recuperare i commit se dimentichi.

Esercitazione