git clean

O que o git clean faz

O comando git clean remove arquivos não rastreados do seu diretório de trabalho. Um arquivo não rastreado é aquele que existe no disco, mas que o Git ainda não está acompanhando, ou seja, nunca foi adicionado com git add e não está no índice.

Isso diferencia o git clean dos outros comandos de desfazer:

• git reset move a ponta do branch e pode desmarcar alterações rastreadas.
• git checkout restaura arquivos rastreados para um estado anterior.
• git clean exclui os arquivos que o Git não está rastreando.

Juntos, eles cobrem toda a árvore de trabalho: reset/checkout lidam com conteúdo rastreado e em estágio, enquanto clean cuida do restante. Um uso típico é limpar artefatos de compilação, arquivos gerados ou sobras de experimentos para que você comece com uma cópia limpa da árvore confirmada.

git clean é irreversível. Ele exclui arquivos diretamente do sistema de arquivos, e não para uma área recuperável como o stash. Não existe desfazer para o git clean. Sempre faça uma prévia com uma execução simulada (-n) primeiro.

O exemplo abaixo configura um repositório com um item rastreado e vários itens não rastreados para que você possa ver a diferença:

Configurar um repositório de exemplo

mkdir test_directory
cd test_directory/
git init .
#Initialized empty Git repository in /Users/kev/code/test_directory/.git/
echo "tracked file" > ./test_tracked_file
git add ./test_tracked_file
echo "untracked" > ./test_untracked_file
mkdir ./test_untracked_dir && touch ./test_untracked_dir/file
git status
#On branch master
#No commits yet
#Changes to be committed:
#  (use "git rm --cached <file>..." to unstage)
#        new file:   test_tracked_file
#Untracked files:
#  (use "git add <file>..." to include in what will be committed)
#        test_untracked_dir/
#        test_untracked_file

Após executar isso, você terá um repositório novo com um arquivo em estágio, test_tracked_file, além de um arquivo não rastreado (test_untracked_file) e um diretório não rastreado (test_untracked_dir). O git status os relata em seções separadas, exatamente a divisão que o git clean considera. Tudo o que se segue opera neste repositório.

Por que o force é necessário

Execute o comando sem argumentos e o Git recusa:

git clean
#fatal: clean.requireForce defaults to true and neither -i, -n, nor -f given; refusing to clean

Como a exclusão é permanente, o Git não executa a operação sem que você opte por -f (force), -n (execução simulada) ou -i (interativo). Você pode alterar o padrão com a configuração git config clean.requireForce, mas mantê-la ativada é a escolha mais segura.

Opções e usos comuns

O comportamento do git clean é controlado quase inteiramente por um conjunto de flags curtas, que se combinam livremente.

-n: execução simulada (prévia)

A flag -n (ou --dry-run) lista o que seria removido sem excluir nada. Torne este seu primeiro passo padrão.

git clean -n
#Would remove test_untracked_file

A saída menciona test_untracked_file. Observe que o diretório não rastreado não está listado, pois por padrão o git clean ignora diretórios (veja -d abaixo).

-f: forçar a exclusão

A flag -f (ou --force) realiza a exclusão de fato. É obrigatória, a menos que clean.requireForce esteja definido como false.

git clean -f
#Removing test_untracked_file

O test_untracked_file agora foi removido; um git status subsequente não o lista mais. Por padrão, git clean -f age sobre todos os arquivos não rastreados no diretório atual. Arquivos correspondidos pelo .gitignore são mantidos, a menos que você adicione -x (abaixo).

Para limitar a operação a um local específico, passe um caminho:

git clean -f path/to/dir

-d: incluir diretórios não rastreados

Por padrão, o git clean pula diretórios não rastreados. Adicione -d para removê-los também. Combine com -n para uma prévia e depois -f para confirmar:

git clean -dn
#Would remove test_untracked_dir/
#Would remove test_untracked_file
git clean -df
#Removing test_untracked_dir/
#Removing test_untracked_file

Com -d, a execução simulada agora lista o diretório além do arquivo não rastreado, e a execução forçada remove ambos, excluindo o diretório e tudo dentro dele.

-x: incluir arquivos ignorados

Normalmente, o git clean respeita o .gitignore. A flag -x instrui a também excluir arquivos ignorados, como node_modules/, saída de compilação ou pastas de editor como .idea/. Isso é poderoso e fácil de se arrepender, portanto, sempre faça uma execução simulada primeiro.

git clean -xn
#Would remove .idea/
#Would remove build/

-x se combina com as outras flags. A combinação abaixo apaga arquivos não rastreados, diretórios não rastreados e arquivos ignorados de uma vez — o equivalente a "redefinir este checkout para exatamente o que está confirmado":

git clean -xdf

Referência rápida

Modo interativo

Se você não tem certeza do que deve ser removido, execute o git clean no modo interativo com a flag -i. É a forma mais segura de limpar uma árvore de trabalho bagunçada, pois nada é excluído até você confirmar. O exemplo abaixo também adiciona -d para que os diretórios sejam incluídos. O Git exibe os itens candidatos e então um prompt What now> com seis comandos:

git clean -di
#Would remove the following items:
#  test_untracked_dir/ test_untracked_file
#*** Commands ***
#    1: clean                2: filter by pattern    3: select by numbers
#    4: ask each             5: quit                 6: help
#What now>

Veja o que cada comando faz.

6 — help. Digite 6 para exibir uma descrição de cada comando:

What now> 6
#clean               - start cleaning files and directories
#filter by pattern   - exclude items from deletion
#select by numbers   - select items to be deleted by numbers
#ask each            - confirm each deletion (like "rm -i")
#quit                - stop cleaning
#help                - this screen
#?                   - help for prompt selection

1 — clean. Exclui os itens atualmente listados e sai:

What now> 1
#Removing test_untracked_dir/
#Removing test_untracked_file

2 — filter by pattern. Permite excluir itens por glob. Aqui, o padrão *_file remove test_untracked_file da lista de exclusão, deixando apenas o diretório na fila:

What now> 2
#test_untracked_dir/ test_untracked_file
#Input ignore patterns>> *_file
#test_untracked_dir/

3 — select by numbers. Refina a lista pelo número do item em vez de padrão. O Git numera cada candidato e você digita os que deseja manter:

What now> 3
#           1: test_untracked_dir/  2: test_untracked_file
#Select items to delete>>

4 — ask each. Percorre cada candidato com um prompt y/N, como rm -i. Responda N para manter um item:

What now> 4
#Remove test_untracked_dir/ [y/N]? N
#Remove test_untracked_file [y/N]? N

5 — quit. Sai do modo interativo sem excluir nada:

What now> 5
#Bye.

git clean vs. stash e reset

O git clean afeta apenas arquivos não rastreados, portanto, use-o quando quiser descartar trabalho em vez de salvá-lo. Se você puder querer as alterações de volta mais tarde, prefira uma destas opções:

• git stash — armazena modificações rastreadas (e, com -u, arquivos não rastreados) para que você possa restaurá-las depois. Reversível.
• git reset — move a ponta do branch e desmarca ou descarta alterações rastreadas.
• git checkout — restaura arquivos rastreados para o estado confirmado.

Uma redefinição completa comum de uma árvore de trabalho é combinar reset para conteúdo rastreado com clean para conteúdo não rastreado:

git reset --hard   # discard tracked changes
git clean -xdf     # remove untracked and ignored files

Após esses dois comandos, o diretório de trabalho corresponde exatamente ao último commit, sem nenhum arquivo restante de qualquer tipo.

Prática