git restore

Cosa fa git restore

Il comando git restore copia una versione pulita di un file nel tuo working tree, nell'area di staging, o in entrambi. Introdotto in Git 2.23 insieme a git switch, ha assunto i compiti a livello di file che in precedenza erano nascosti all'interno del sovraccarico comando git checkout. Il suo scopo è rispondere a una sola domanda: da dove deve provenire la copia corretta di questo file e dove deve essere collocata?

Per usarlo al meglio, è utile conoscere i "tre alberi" di Git: il working tree (i file che modifichi su disco), l'index (chiamato anche area di staging — ciò che git add scrive e che il prossimo commit acquisirà), e HEAD (lo snapshot dell'ultimo commit). git restore sposta sempre il contenuto da una sorgente verso una destinazione tra questi. Due flag controllano questo comportamento:

• --source=<rev> — da dove proviene la copia pulita. Per default è l'index, oppure HEAD quando si usa --staged.
• --staged e/o --worktree — dove viene scritta la copia. Per default è --worktree.

Questa pagina illustra gli usi quotidiani: scartare modifiche, rimuovere file dallo stage, ripristinare da un commit precedente, recuperare un file eliminato e le differenze tra restore, reset e revert.

Scartare le modifiche nel working tree

Per default, git restore sovrascrive un file nella tua directory di lavoro con la versione dell'area di staging (l'index). Se hai modificato un file e vuoi annullare quelle modifiche:

git restore index.html

Il file torna al suo ultimo stato nello stage (o al suo stato in HEAD se non era mai stato aggiunto allo stage). Poiché questa operazione è distruttiva — le modifiche non staged vengono perse definitivamente e non possono essere recuperate con git reflog — Git assegna deliberatamente all'operazione un nome chiaro ed esplicito invece di nasconderla dietro checkout.

Per scartare le modifiche in più file contemporaneamente, passa una directory o un pathspec. Questo è uno dei pochi comandi git restore che può cancellare molto lavoro con una sola pressione di tasto, quindi verifica prima cosa non è ancora stato committato con git status:

git restore .          # discard all changes in the current directory
git restore src/       # discard all changes under src/

Rimuovere dallo stage con --staged

Per rimuovere un file dall'area di staging senza modificarne il contenuto su disco, usa --staged. Questo copia la versione da HEAD nuovamente nell'index, lasciando intatte le modifiche nel working tree:

git restore --staged index.html

Questo è il moderno sostituto di git reset HEAD <file>, ed è esattamente ciò che Git suggerisce nel testo dei suggerimenti quando esegui git status dopo aver aggiunto qualcosa allo stage:

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   index.html

Ripristinare da un commit specifico

L'opzione --source permette di recuperare il contenuto di un file da qualsiasi commit, branch o tag — non solo dall'index o da HEAD:

git restore --source=HEAD~2 config.yml

Questo riporta un singolo file a com'era due commit fa. Nota cosa non fa: non crea un commit e non sposta alcun puntatore di branch. Il vecchio contenuto arriva nel working tree come una normale modifica non staged, pronta per essere ispezionata, aggiunta allo stage e committata. Puoi usare un nome di branch (--source=main) o un tag (--source=v1.0) con la stessa facilità.

Recuperare un file eliminato

Se elimini per sbaglio un file tracciato e non hai ancora committato l'eliminazione, git restore lo riporta dall'index o da HEAD:

git restore app.js

Poiché il file esiste ancora in uno snapshot valido, Git lo riscrive su disco esattamente com'era. (Se hai già committato l'eliminazione, ripristinalo dall'ultimo commit prima di quello: git restore --source=HEAD~1 app.js.)

Azzerare entrambe le copie in una volta

Combinando --staged e --worktree si reimposta un file completamente — sia la copia nello stage che quella su disco — all'ultimo stato in HEAD:

git restore --staged --worktree index.html

Questo è il comando "fai in modo che questo file appaia esattamente come nell'ultimo commit, indipendentemente da cosa ho fatto". Scarta sia le modifiche staged che quelle non staged in un unico passaggio.

Ripristinare una parte di un file

Come git add e git checkout, git restore supporta la modalità patch. Con -p (o --patch), Git ti guida attraverso ogni hunk di modifica e ti chiede se scartarlo, così puoi eliminare alcune modifiche mantenendone altre:

git restore -p index.html

Questo è utile quando hai apportato diverse modifiche non correlate in un unico file e vuoi annullare solo un esperimento specifico.

Opzioni comuni

restore vs reset vs revert

Questi tre comandi si confondono facilmente perché tutti "annullano" qualcosa, ma operano a livelli diversi:

• git restore opera sui file nel working tree e nell'index. Non sposta mai i puntatori di branch né riscrive la cronologia.
• git reset sposta la punta del branch corrente e può modificare l'area di staging — opera a livello di commit.
• git revert crea un nuovo commit che annulla uno precedente, lasciando intatta la cronologia esistente.

Usa restore quando vuoi semplicemente che un file appaia come appariva altrove. Se vuoi eliminare interi commit o spostare un branch, quello è il compito di git reset. Se le modifiche sono già state pushate e condivise, usa git revert per non riscrivere una cronologia da cui altri dipendono. Per accantonare temporaneamente le modifiche invece di scartarle, vedi git stash.

Pratica