git rm

Il comando git rm rimuove uno o più file da un repository Git. Questa pagina spiega cosa fa git rm, le opzioni che accetta, in cosa differisce dall'rm della shell, come annullare una rimozione e alcune ricette pratiche.

Cosa fa git rm

git rm rimuove i file tracciati — quelli che Git già conosce. Per impostazione predefinita, elimina il file sia dalla directory di lavoro (i file sul disco) che dall'indice di staging (lo snapshot che Git registrerà nel commit successivo), poi mette in staging quella cancellazione affinché venga inclusa nel prossimo commit.

Alcuni fatti utili da conoscere in anticipo:

• git rm funziona solo su file tracciati. Fallisce con fatal: pathspec '...' did not match any files se si tenta di rimuovere un file non tracciato — Git non seguiva quel file, quindi non c'è nulla da registrare.
• Può rimuovere un file solo dall'indice di staging (con --cached), ma non può rimuovere un file solo dalla directory di lavoro — quella è semplicemente una cancellazione ordinaria, che è ciò che fa il comando rm della shell.
• Non rimuove branch, tag o commit. Agisce solo sui file.
• La rimozione non è permanente finché non si esegue un commit. Prima di allora, è facile annullarla (vedi Annullare git rm).

Un tipico flusso di lavoro è il seguente:

git rm notes.txt        # deletes notes.txt and stages the deletion
git commit -m "Remove notes.txt"

Opzioni del comando git rm

Annullare git rm

git rm aggiorna l'indice di staging e la directory di lavoro, ma la modifica non è permanente finché non si esegue un commit. Fino ad allora è possibile recuperare il file con i normali comandi Git. Il comando da usare dipende da quanto si vuole tornare indietro.

Prima di committare la rimozione

Per rimuovere dallo staging la cancellazione ma mantenere il file eliminato sul disco, ripristinare la voce dell'indice a HEAD:

git reset HEAD <file>

Per ripristinare completamente il file — sia nell'indice di staging che nella directory di lavoro — usare il moderno comando git restore:

git restore --staged --worktree <file>

I vecchi equivalenti git reset HEAD <file> seguito da git checkout -- <file> funzionano ancora, ma git restore è il metodo consigliato nelle versioni correnti di Git.

Dopo aver committato la rimozione

Se è già stato creato un commit che registra la cancellazione, il file esiste solo nella cronologia. Trova un punto sicuro con git reflog e ripristina il file da un commit in cui esisteva ancora:

git restore --source=HEAD~1 <file>

Git rm vs rm

Il comando rm della shell e git rm eliminano entrambi i file dal disco, ma Git li tratta in modo molto diverso.

Quando si esegue il semplice rm della shell su un file tracciato, il repository Git si accorge che il file è sparito e mostra la cancellazione come una modifica non in staging. Bisogna ancora eseguire git add (o git add -u) per registrarla nell'indice di staging prima di fare il commit.

git rm esegue entrambi i passaggi in una volta sola: elimina il file e mette in staging la cancellazione, così è pronto per il commit successivo immediatamente.

# Shell rm — deletion is unstaged, needs git add afterwards
rm notes.txt
git add notes.txt

# git rm — deletion is staged in one step
git rm notes.txt

Rimuovere file solo dall'indice

Un caso comune è mantenere un file sul disco ma interrompere il tracciamento da parte di Git — ad esempio un file di configurazione o un artefatto di build committato accidentalmente e che ora si vuole ignorare. Usare --cached:

git rm --cached secrets.env

Il file rimane nella directory di lavoro; viene rimossa solo la copia tracciata. Aggiungere il percorso a .gitignore in seguito in modo che non venga ri-aggiunto.

Esempi

Rimuovere tutti i file .txt in una cartella (wildcard):

git rm folder/\*.txt

La barra rovescia prima di * impedisce alla shell di espandere il glob, così Git stesso lo espande sui file tracciati in folder/. Questo corrisponde anche ai percorsi nelle sottodirectory, non solo ai figli diretti.

Rimozione forzata di file con modifiche non committate:

git rm -f git-*.sh

Senza -f, git rm si rifiuta di eliminare un file il cui contenuto nella directory di lavoro o in staging differisce da HEAD, per proteggerti dalla perdita di lavoro. Il flag force ignora quel controllo.

Anteprima di una rimozione senza eliminare nulla:

git rm -r --dry-run logs/

Questo elenca i file che verrebbero rimossi in logs/, permettendo di confermare l'insieme prima di eseguire il comando per davvero.

Rimuovere file già eliminati con shell rm

Se sono stati eliminati diversi file tracciati con il comando rm della shell e si vuole registrarli tutti nel commit successivo, metti in staging tutte le cancellazioni in una volta:

git add -u
git commit -m "Remove obsolete files"

git add -u mette in staging gli aggiornamenti ai file già tracciati, incluse le cancellazioni. In alternativa, è possibile costruire un elenco dei percorsi eliminati e inviarlo tramite pipe a git rm --cached:

git diff --name-only --diff-filter=D -z | xargs -0 git rm --cached

--diff-filter=D seleziona solo i percorsi eliminati, e la coppia -z / -0 usa separatori NUL in modo che i nomi di file con spazi vengano gestiti in modo sicuro.

Esercitazione