Git remove untracked files: guia seguro do git clean

TL;DR: para remover untracked files no git, rode git clean -fd — mas sempre pré-visualize com git clean -nd antes, porque o clean apaga de vez e eles nunca passam pela lixeira. Use -f para arquivos, -fd para arquivos e diretórios, e -fdx se o output de build do gitignore também deve ir embora. A reclamação mais comum de todas — “o git clean não remove meus untracked files” — quase sempre significa que os arquivos vivem dentro de um diretório untracked (adicione -d) ou que são arquivos ignorados (adicione -x). Bagunça untracked é o efeito colateral natural de experimentos, builds e scripts que nasceram de clones; este guia mostra como pré-visualizar cada remoção, apagar arquivos de um único diretório e quais combinações nunca rodar num repositório que você valoriza.

O que significa “untracked files” no git status?

Untracked significa que o git vê o arquivo no disco, mas nunca foi avisado para rastreá-lo — ele não está no index e não tem histórico de commits. O git status agrupa tudo em três baldes:

$ git status --short
 M src/app.ts        # modificado: rastreado, com mudanças
?? notes.txt         # untracked: arquivo novo que o git não conhece
?? build/            # diretório untracked: totalmente novo para o git

Essa distinção importa porque cada balde pede uma ferramenta de remoção diferente. Arquivos rastreados mas alterados voltam com git restore ou se resolvem num commit — o git clean não os toca. Só as linhas ?? são território do git clean. Arquivos ignorados (tudo que casa com o .gitignore) são um quarto balde escondido: nem aparecem como ??, e o git clean os pula a menos que você peça explicitamente com -x.

Se o seu problema real é um arquivo rastreado que nunca devia ter sido commitado, limpar é a ferramenta errada — isso é trabalho para git rm --cached, ou para reverter o último commit, como cobre o git undo last commit: mantendo as mudanças.

Como remover untracked files no git?

O comando central é git clean -f. Sem -f, o git se recusa a apagar qualquer coisa e só imprime um aviso — um trilho de segurança de propósito. A rotina completa fica assim:

# 1. Veja exatamente o que será apagado (dry run — não apaga nada)
git clean -nd

# Would remove:
# notes.txt
# build/
# scratch/

# 2. Confirme que não há nada precioso na lista, então apague de verdade
git clean -fd

Flag por flag:

• -f / --force — obrigatória. É ela que de fato apaga os untracked files.
• -d — recursa em diretórios untracked. O -f sozinho só remove arquivos untracked no nível de cima e avisa quais diretórios se recusou a tocar.
• -n / --dry-run — mostra o que seria removido. Rode sempre primeiro.
• -x — também apaga arquivos ignorados (node_modules, output de build, .env).
• -X — apaga apenas os ignorados, mantendo os untracked que não são ignorados.
• -i — modo interativo; útil quando a lista do dry-run é grande.

Um hábito que vale copiar: trate o git clean -nd como o git diff — você olha antes de commitar, olha antes de limpar.

Por que o git clean não está removendo meus untracked files?

Três causas reais, na ordem de frequência com que mordem:

1. Os arquivos estão dentro de um diretório untracked. Com apenas -f, o git remove os arquivos untracked soltos, mas para nos diretórios — chegando a reportar Would remove build/ sem apagar nada numa execução real. Adicione -d:

git clean -fd

2. Os arquivos estão no gitignore. node_modules/, dist/, .venv/ — caminhos ignorados são invisíveis para um clean comum. O dry run não os lista, e o clean também não os remove. Peça explicitamente:

git clean -fdx   # untracked + arquivos e diretórios ignorados

3. Um repositório git aninhado ou submodule está no caminho. O git nunca apaga o conteúdo do repositório de outro por fora. Remova o submodule direito ou passe --force duas vezes (git clean -ffd) — e prefira a primeira opção.

Se o dry run não lista nada mas o git status continua mostrando ??, você provavelmente está na working tree errada — rode git rev-parse --show-toplevel e confirme que está dentro do repositório que pretendia limpar.

Como remover untracked files de um diretório específico apenas?

Escopo o clean passando um caminho — todo o resto fica intocado:

git clean -fd build/          # só dentro de build/
git clean -fd src/generated   # uma árvore específica

Essa é a resposta para “quero remover os untracked files e pastas de build/, mas manter minhas anotações de rascunho na raiz do repositório”. O caminho é relativo ao seu diretório atual: rodando da raiz, o escopo é o repositório inteiro; rodando de um subdiretório, é aquela subárvore.

Como remover untracked files sem apagá-los?

Quando o dry run mostra arquivos que você pode querer depois, não aposte — preserve primeiro, limpe depois:

# Manda os untracked files para o stash (incluindo os ignorados com -a) sem apagar
git stash push --include-untracked
git clean -fd                      # a árvore fica limpa
git stash pop                      # traz de volta quando precisar

O git stash -u tira os untracked files da árvore, mas os mantém recuperáveis — essa é a semântica de “remover sem apagar” que as pessoas realmente procuram. Para um preview que você pode guardar, git clean -nd > clean-plan.txt dá a lista exata antes de se comprometer com qualquer coisa. Não existe undo depois do git clean -f: apagado significa ido.

git clean vs git rm vs git restore: quando usar cada um?

Comando	O que toca	Remove do disco	Use quando
git clean -fd	Untracked files/dirs	Sim	Apagar arquivos que o git nunca rastreou
git clean -fdx	Untracked + ignorados	Sim	Reset total incluindo node_modules, output de build
git rm <file>	Arquivos rastreados	Sim (staged)	Apagar um arquivo e registrar a remoção no git
git rm --cached <file>	Arquivos rastreados	Não	Parar de rastrear um arquivo, mantê-lo no disco
git restore <file>	Arquivos rastreados	Não	Descartar edições locais, manter o arquivo

A regra de uma linha: o clean cuida do que o git não conhece; rm e restore cuidam do que ele conhece. Confundir os dois é como se perde trabalho — rodar git clean -fdx acreditando que ele se comporta como git restore.

Onde você nunca deve rodar o git clean?

Dois hábitos para evitar de cara:

1. Nunca rode git clean -fdx às cegas num monorepo ou workspace. Ele apaga todo diretório ignorado — ou seja, todo node_modules, todo virtualenv, todo .env local da árvore. Recuperar isso pode significar uma hora de reinstalação, e um .env apagado pode não ter volta alguma.
2. Nunca crie alias do clean com force embutido. git config alias.wipe "clean -fd" parece eficiente até você errar o caminho na digitação. Mantenha o dry run a um toque (git clean -nd) e transforme em ritual de dois comandos: preview, depois delete.

Também vale saber: limpar os untracked files logo antes de um pull [sync a fork with upstream] mantém a superfície de merge pequena — uma árvore arrumada é o seguro contra conflitos mais barato que existe: sincronize um fork com o upstream, passo a passo.

O fluxo seguro do git clean, resumido

git status --short        # o que tem na árvore?
git clean -nd             # preview: o que SERIA apagado?
git clean -fd             # apaga untracked files + diretórios
git clean -fdX            # (opcional) limpa só o output de build ignorado
git status --short        # confirma: working tree limpa

Preview, apagar, verificar — trinta segundos, zero arrependimento, e o git status finalmente volta a dizer limpo.