Rimuovere i file untracked in Git: guida sicura a git clean

TL;DR: per rimuovere i file untracked in git lancia git clean -fd — ma fai sempre prima l’anteprima con git clean -nd, perché clean cancella per sempre e i file non finiscono mai nel cestino. Usa -f per i file, -fd per file e directory, e -fdx se anche l’output di build gitignored deve andare. Il reclamo più comune in assoluto — «git clean non mi rimove i file untracked» — quasi sempre significa che i file stanno dentro una directory non tracciata (aggiungi -d) oppure che sono file ignorati (aggiungi -x). Il disordine untracked è il sottoprodotto normale di esperimenti, build e script legati ai cloni; questa guida mostra come vedere in anteprima ogni cancellazione, rimuovere i file di una sola directory e quali combinazioni non lanciare mai in un repository a cui tieni.

Cosa significa «file untracked» in git status?

Untracked significa che git vede il file sul disco ma non gli è mai stato detto di tracciarlo: non è nell’indice e non ha storia di commit. git status raggruppa tutto in tre bucket:

$ git status --short
 M src/app.ts        # modificato: tracciato, con modifiche
?? notes.txt         # untracked: nuovo file che git non conosce
?? build/            # directory untracked: per git è tutta nuova

La distinzione conta perché ogni bucket richiede uno strumento di rimozione diverso. I file tracciati ma modificati si ripristinano con git restore o si chiudono in un commit — git clean non li tocca. Solo le righe ?? sono territorio di git clean. I file ignorati (tutto ciò che matcha .gitignore) sono un quarto bucket nascosto: non compaiono nemmeno come ??, e git clean li salta a meno che tu non dia il consenso esplicito con -x.

Se il tuo vero problema è un file tracciato che non doveva mai finire nel repository, la pulizia è lo strumento sbagliato: è un lavoro da git rm --cached, o un reset dell’ultimo commit come raccontato in git undo last commit: keep the changes.

Come rimuovo i file untracked in git?

Il comando di base è git clean -f. Senza -f git si rifiuta di cancellare qualsiasi cosa e si limita a stampare un avviso — una protezione voluta. La routine completa è questa:

# 1. Guarda esattamente cosa verrà cancellato (dry run — non cancella nulla)
git clean -nd

# Rimuoverebbe:
# notes.txt
# build/
# scratch/

# 2. Conferma che nella lista non c'è niente di prezioso, poi cancella davvero
git clean -fd

Flag per flag:

• -f / --force — obbligatorio. Cancella davvero i file untracked.
• -d — scende nelle directory non tracciate. Un -f da solo rimuove solo i file untracked al livello corrente e segnala le directory che si è rifiutato di toccare.
• -n / --dry-run — mostra cosa sarebbe rimosso. Lanciala sempre per prima.
• -x — cancella anche i file ignorati (node_modules, output di build, .env).
• -X — cancella solo i file ignorati, tenendo quelli untracked ma non ignorati.
• -i — modalità interattiva; utile quando la lista del dry-run è lunga.

Un’abitudine da copiare: tratta git clean -nd come git diff — guardi prima di fare commit, guardi prima di pulire.

Perché git clean non mi rimove i file untracked?

Tre cause reali, in ordine di quanto spesso mordono:

1. I file sono dentro una directory non tracciata. Con il solo -f, git rimuove i file untracked sparsi ma si ferma alle directory, arrivando a riportare Would remove build/ senza cancellarla in una esecuzione reale. Aggiungi -d:

git clean -fd

2. I file sono gitignored. node_modules/, dist/, .venv/ — i percorsi ignorati sono invisibili a un clean semplice. Il dry-run non li elenca, e il clean non li rimuove. Dai il consenso esplicito:

git clean -fdx   # file e directory untracked + ignorati

3. Un repository git annidato o un submodule si mette di traverso. Git non cancella mai il contenuto del repository di un altro dall’esterno. Rimuovi il submodule per bene oppure passa --force due volte (git clean -ffd), e preferisci la prima strada.

Se il dry-run non elenca nulla ma git status mostra ancora voci ??, probabilmente sei nel working tree sbagliato: lancia git rev-parse --show-toplevel e verifica di essere dentro il repository che intendevi pulire.

Come rimuovo i file untracked solo da una directory specifica?

Limita il campo passando un percorso — tutto il resto resta intatto:

git clean -fd build/          # solo dentro build/
git clean -fd src/generated   # un singolo albero specifico

Questa è la risposta a «voglio rimuovere i file e le cartelle untracked in build/ ma tenere i miei appunti nella radice del repository». Il percorso è relativo alla tua directory corrente: dalla radice del repo lo scope è l’intero repository, da una sottodirectory è quel sottoalbero.

Come rimuovo i file untracked senza cancellarli?

Quando il dry-run mostra file che potresti volere più avanti, non giocare d’azzardo — salva prima, pulisci dopo:

# Stash dei file untracked (inclusi gli ignorati con -a) senza cancellarli
git stash push --include-untracked
git clean -fd                      # l'albero è pulito
git stash pop                      # li riporti fuori quando servono

git stash -u sposta i file untracked fuori dall’albero ma li tiene recuperabili — è la semantica «rimuovere senza cancellare» che la gente cerca davvero. Per un’anteprima che puoi conservare, git clean -nd > clean-plan.txt ti dà la lista esatta prima di impegnarti a qualcosa. Dopo git clean -f non esiste undo: cancellato significa perso.

git clean vs git rm vs git restore: quale e quando?

Comando	Tocca	Rimuove dal disco	Usalo quando
git clean -fd	File/directory untracked	Sì	Cancellare file che git non ha mai tracciato
git clean -fdx	Untracked + ignorati	Sì	Reset totale, node_modules e output di build inclusi
git rm <file>	File tracciati	Sì (in stage)	Cancellare un file e registrare la cancellazione in git
git rm --cached <file>	File tracciati	No	Smettere di tracciare un file, tenerlo su disco
git restore <file>	File tracciati	No	Scartare le modifiche locali, tenere il file

La regola in una riga: clean gestisce ciò che git non conosce; rm e restore gestiscono ciò che conosce. Confonderli è il modo in cui la gente perde lavoro — lanciare git clean -fdx credendo che si comporti come git restore.

Su cosa non devi mai lanciare git clean?

Due abitudini da evitare senza eccezioni:

1. Non lanciare mai git clean -fdx alla cieca in un monorepo o in un workspace. Cancella ogni directory ignorata — cioè ogni node_modules, ogni virtualenv, ogni .env locale nell’albero. Recuperarli può significare un’ora di reinstallazione, e un .env cancellato potrebbe non essere recuperabile per niente.
2. Non creare mai un alias di clean con la forza precotta. git config alias.wipe "clean -fd" sembra efficiente finché non sbagli a scrivere il percorso. Tieni il dry-run a un tasto di distanza (git clean -nd) e rendilo un rituale di due comandi: anteprima, poi cancellazione.

Vale anche sapere: pulire i file untracked subito prima di un pull [sincronizzare la fork con l'upstream] tiene piccola la superficie di merge — un albero in ordine è l’assicurazione contro i conflitti più economica che esista: sincronizzare una fork con l’upstream, passo per passo.

Il workflow sicuro di git clean, in sintesi

git status --short        # cosa c'è nell'albero?
git clean -nd             # anteprima: cosa ANDREBBE via?
git clean -fd             # cancella file e directory untracked
git clean -fdX            # (opzionale) ripulisce solo l'output di build ignorato
git status --short        # conferma: working tree pulito

Anteprima, cancellazione, verifica — trenta secondi, zero rimpianti, e git status finalmente torna a dire clean.