git rm
Saiba o que o comando git rm faz, como usá-lo, como desfazê-lo e veja a diferença entre o rm do shell e o git rm.
O comando git rm remove um ou mais arquivos de um repositório Git. Esta página explica o que o git rm faz, as opções que aceita, como difere do rm do shell, como desfazer uma remoção e algumas receitas práticas.
O que o git rm faz
git rm remove arquivos rastreados — arquivos que o Git já conhece. Por padrão, ele exclui o arquivo tanto do diretório de trabalho (os arquivos no seu disco) quanto do índice de staging (o snapshot que o Git registrará no próximo commit), e depois prepara essa exclusão para ser incluída no seu próximo commit.
Alguns fatos importantes a saber de antemão:
git rmsó funciona em arquivos rastreados. Ele falha comfatal: pathspec '...' did not match any filesse você tentar remover um arquivo não rastreado — o Git não estava acompanhando esse arquivo, então não há nada a registrar.- Ele pode remover um arquivo apenas do índice de staging (com
--cached), mas não pode remover um arquivo somente do diretório de trabalho — isso é apenas uma exclusão simples, que é o que ormdo shell faz. - Ele não remove branches, tags ou commits. Ele só afeta arquivos.
- A remoção não é permanente até você fazer um commit. Antes disso, é fácil desfazê-la (veja Desfazendo o git rm).
Um fluxo de trabalho típico é assim:
git rm notes.txt # deletes notes.txt and stages the deletion
git commit -m "Remove notes.txt"Opções do comando git rm
| Opção | O que faz |
|---|---|
<file>… | O(s) caminho(s) a remover. Aceita globs de arquivo como *.txt. |
-f, --force | Substitui a verificação de segurança que compara o arquivo em HEAD com o índice de staging e o diretório de trabalho. Necessário quando o arquivo tem alterações não commitadas. |
-n, --dry-run | Executa o comando sem remover nada. Apenas lista os arquivos que seriam removidos. |
-r | Recursivo. Necessário para remover um diretório junto com todo o seu conteúdo. |
-- | Separa opções de nomes de arquivo. Use quando um nome de arquivo pode ser confundido com uma opção (por exemplo, um arquivo literalmente chamado -f). |
--cached | Remove o arquivo apenas do índice de staging. A cópia no diretório de trabalho é mantida intacta. |
--ignore-unmatch | Encerra com status 0 mesmo quando nenhum arquivo corresponder. Útil em scripts que não devem falhar em um caminho ausente. |
-q, --quiet | Suprime a saída por arquivo que o git rm normalmente imprime. |
Desfazendo o git rm
git rm atualiza o índice de staging e o diretório de trabalho, mas a alteração não é permanente até você fazer um commit. Até lá, você pode recuperar o arquivo com comandos Git comuns. O que você precisa depende de até onde deseja reverter.
Antes de fazer o commit da remoção
Para remover a remoção do staging mas manter o arquivo excluído no disco, redefina a entrada do índice de volta para HEAD:
git reset HEAD <file>Para restaurar o arquivo completamente — tanto no índice de staging quanto no diretório de trabalho — use o comando moderno git restore:
git restore --staged --worktree <file>Os equivalentes mais antigos git reset HEAD <file> seguido de git checkout -- <file> ainda funcionam, mas git restore é a forma recomendada no Git atual.
Depois de fazer o commit da remoção
Se você já criou um commit que registra a exclusão, o arquivo vive apenas no histórico. Encontre um ponto seguro com git reflog e restaure o arquivo a partir de um commit onde ele ainda existia:
git restore --source=HEAD~1 <file>Git rm vs rm
O rm do shell e o git rm ambos excluem arquivos do disco, mas o Git os trata de forma muito diferente.
Quando você executa o rm simples do shell em um arquivo rastreado, o repositório Git percebe que o arquivo desapareceu e mostra a exclusão como uma alteração não preparada para staging. Você ainda precisa executar git add (ou git add -u) para registrá-la no índice de staging antes de fazer o commit.
git rm faz os dois passos de uma vez: ele exclui o arquivo e prepara a exclusão para staging, então já está pronto para o próximo commit imediatamente.
# 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.txtRemovendo arquivos apenas do índice
Um caso comum é manter um arquivo no disco mas fazer o Git parar de rastreá-lo — por exemplo, um arquivo de configuração ou artefato de build que você acidentalmente fez commit e agora quer ignorar. Use --cached:
git rm --cached secrets.envO arquivo permanece no seu diretório de trabalho; apenas a cópia rastreada é removida. Adicione o caminho ao .gitignore depois para que ele não seja adicionado novamente.
Exemplos
Remover todos os arquivos .txt em uma pasta (curinga):
git rm folder/\*.txtA barra invertida antes de * impede que o shell expanda o glob, então o próprio Git o expande pelos arquivos rastreados em folder/. Isso corresponde a caminhos em subdiretórios também, não apenas filhos diretos.
Forçar a remoção de arquivos com alterações não commitadas:
git rm -f git-*.shSem -f, o git rm se recusa a excluir um arquivo cujo conteúdo no diretório de trabalho ou em staging difere de HEAD, para protegê-lo de perder trabalho. O flag de força substitui essa verificação.
Visualizar uma remoção sem excluir nada:
git rm -r --dry-run logs/Isso lista os arquivos que seriam removidos em logs/, permitindo confirmar o conjunto antes de executar o comando de verdade.
Removendo arquivos já excluídos com o rm do shell
Se você excluiu vários arquivos rastreados com o rm do shell e quer registrar todos eles no seu próximo commit, prepare todas as exclusões de uma vez:
git add -u
git commit -m "Remove obsolete files"git add -u prepara as atualizações para arquivos já rastreados, incluindo exclusões. Alternativamente, construa uma lista dos caminhos excluídos e passe-os para git rm --cached:
git diff --name-only --diff-filter=D -z | xargs -0 git rm --cached--diff-filter=D seleciona apenas caminhos excluídos, e o par -z / -0 usa separadores NUL para que nomes de arquivos com espaços sejam tratados com segurança.