Como remover arquivos de repositórios Git sem quebrar seu projeto

Remover arquivos no Git nem sempre é tão simples quanto parece. Você deleta um arquivo no seu sistema, mas isso não significa que ele sumiu do repositório. Ele pode continuar no histórico ou, pior, acabar sendo commitado por engano — como um arquivo de configuração ou uma chave de API.

Neste guia, você vai aprender como remover arquivos do Git. Vamos começar com comandos básicos como git rm e depois avançar para métodos como limpar arquivos não rastreados e editar o histórico de commits.

Pré-requisitos

Antes de remover arquivos com Git, vamos conferir se está tudo pronto.

Primeiro, verifique se o Git está instalado. Abra o terminal e execute:

git --version

Se aparecer um número de versão, está tudo certo. 

Se aparecer um número de versão, está tudo certo.

Você também pode instalar um cliente Git com interface gráfica, como GitHub Desktop, Sourcetree ou GitKraken, se preferir algo visual. Mas, neste guia, vou usar a linha de comando (Git Bash).

Garanta que você tem permissão para fazer mudanças no repositório, especialmente se fizer parte de um time ou trabalhar com um repositório remoto como GitHub ou GitLab.

Observação: algumas ações de remoção de arquivos não têm como desfazer. Então é uma boa prática fazer backup do projeto ou, pelo menos, conferir duas vezes o estado do repositório antes de rodar comandos que excluem arquivos.

Com isso em ordem, vamos começar.

Remoção básica de arquivos no Git

Há algumas formas de remover arquivos no Git, dependendo do que você quer fazer. Veja opções comuns:

Usando git rm

O comando git rm remove arquivos do seu repositório Git. Ao executá-lo, acontecem duas coisas:

• O Git remove o arquivo do seu diretório de trabalho
• Ele adiciona essa mudança à área de stage para o próximo commit

Mas o Git não apenas deleta o arquivo: ele registra a exclusão no histórico. Depois do commit, o arquivo é oficialmente removido do projeto.

git rm file1.txt

Você pode remover um arquivo, vários arquivos ou um conjunto deles usando curingas.

Por exemplo, para remover todos os arquivos de log:

git rm *.log

Isso diz ao Git para remover todos os arquivos da pasta que terminam com .log. Você pode confirmar a alteração com:

git status

Delete vários arquivos com um único comando git rm. Imagem do autor.

Quer remover todos os arquivos dentro de uma pasta, mas manter a pasta? Use:

git rm temp/*

Isso exclui todos os arquivos dentro da pasta temp sem apagar a pasta.

O Git também adiciona algumas proteções. Se um arquivo tiver mudanças não commitadas, o Git não vai deletá-lo a menos que você force. Use isso apenas se tiver certeza de que as mudanças podem ser descartadas:

git rm -f

Para remover uma pasta inteira e tudo dentro dela, adicione a flag -r:

git rm -r testfolder

Isso remove testfolder e todos os arquivos dentro dela.

Agora, para fazer o commit da mudança, rode o comando:

git commit -m "removed log files”

Opções essenciais do git rm

Aqui estão as opções mais comuns que você vai usar com git rm:

1. <filename>

Uso básico: liste os arquivos que deseja remover:

git rm file1.txt file2.txt

Você também pode usar curingas para remover vários arquivos do mesmo tipo. Por exemplo, para remover todos os arquivos .txt:

git rm *.txt

(Aqui, * significa todos. Ele corresponde a qualquer nome de arquivo que termine com .txt.)

2. --cached

Isso remove o arquivo do repositório, mas o mantém na sua máquina. Digamos que eu adicionei por engano um arquivo sensível, como config.env. Eu não quero esse arquivo no repositório, mas ainda preciso dele localmente. Então eu rodaria:

git rm --cached config.env

Aqui, git rm removeria do repositório e do diretório de trabalho. E --cached faz com que o Git pare de rastrear o arquivo (não será enviado no push), mas o mantém fisicamente no lugar.

Para evitar que ele seja adicionado novamente, inclua-o no .gitignore:

echo config.env >> .gitignore

3. -r

Significa recursivo. Em vez de um arquivo, exclui a pasta e seu conteúdo de forma recursiva. Sem isso, o Git retorna erro ao tentar remover uma pasta.

git rm -r <folder-name>

Aqui, criei uma pasta chamada testfolder e dois arquivos dentro dela: a.txt e b.txt. Em seguida, executei:

git rm -r testfolder

Isso removeu a pasta junto com todos os conteúdos dentro dela

4. --dry-run

Se você não tem certeza do que vai acontecer ao remover um arquivo, use git rm com a opção --dry-run assim:

git rm --dry-run <filename>

É uma forma segura de pré-visualizar o que será removido. 

Ou, se estiver limpando arquivos não rastreados e quiser conferir o que será removido, use:

git clean -n

Isso só mostra o que o comando deletaria.

Análise comparativa de fluxos

Existe mais de uma forma de remover um arquivo no Git. Os métodos podem parecer iguais, mas o comportamento muda.

git rm vs exclusão manual

Vamos pegar um arquivo chamado file.txt. Digamos que eu não preciso mais dele.

Uma forma de removê-lo é deletar diretamente no sistema.

No Linux, macOS ou Git Bash:

rm file.txt

No Windows (prompt de comando): 

del file.txt

Isso exclui o arquivo da sua pasta. Mas o Git ainda não sabe disso. Então você precisa dizer ao Git manualmente que o arquivo foi removido:

git add file.txt

Isso coloca a exclusão em stage para ser incluída no próximo commit.

Se você deletou vários arquivos e não lembra todos, rode:

git add -u

Isso coloca em stage todos os arquivos rastreados que foram alterados ou deletados. Não inclui arquivos não rastreados.

Agora faça o commit da mudança:

git commit -m "Remove file.txt"

Se você usar git rm, tudo acontece em um passo. Ele deleta o arquivo e já coloca a mudança em stage:

git rm file.txtgit commit -m "Remove file.txt"

Sem precisar rodar git add separadamente. Fica mais limpo, e você não esquece de colocar a exclusão em stage.

Resumindo:

• A exclusão manual exige passos extras para o Git captar a mudança.
• Se você esquecer de colocar a exclusão em stage, o Git ainda acha que o arquivo existe, o que pode causar confusão em commits ou merges.
• git rm é mais limpo e seguro quando você quer remover arquivos rastreados de propósito.

Restaurar arquivos deletados no Git

E se você deleta um arquivo e depois percebe que ainda precisa dele? Sem problema. O Git oferece algumas formas de trazê-lo de volta, dependendo de quando você notou o erro.

Se você ainda não fez o commit:

Digamos que você deletou o arquivo, mas ainda não fez o commit da mudança. Dá para restaurar a partir do último commit assim: 

git restore file.txt

Isso traz o arquivo de volta ao seu diretório de trabalho a partir do commit mais recente.

Se você já commitou a exclusão:

Tudo bem também. Primeiro, encontre o último commit em que o arquivo existia:

git log -- file.txt

Percorra o log e copie o hash do commit em que o arquivo ainda estava lá. Depois, rode:

git checkout <commit hash> -- file.txt

Em versões antigas do Git, você podia usar o comando acima. Ele restaura um arquivo de um commit específico, mas também podia trocar de branch.

A partir do Git 2.23, isso foi dividido em dois comandos mais claros:

• git switch (para trocar de branch)
• git restore (para restaurar arquivos)

Se você só quer restaurar um arquivo de um commit, use:

git restore --source=<commit-hash> --file.txt

Isso puxa o arquivo daquele commit e o coloca de volta no seu diretório de trabalho.

Se você não sabe quando o arquivo foi deletado:

Talvez você tenha feito várias mudanças e não lembra quando o arquivo sumiu. Nesse caso, use o git reflog (reference log): 

git reflog

Isso mostra um histórico completo dos seus commits, checkouts, resets — tudo.

Mas o git reflog é apenas local e não funciona em remotos. Se você estiver trabalhando com um repositório remoto, é melhor usar git log -- file.txt para rastrear o histórico daquele arquivo.

Depois que achar o ponto em que o arquivo ainda existia, restaure usando git checkout ou git restore, como vimos.

Corrigir arquivos ausentes no Git

Às vezes arquivos são deletados diretamente no sistema — pelo explorador de arquivos, por um rm no terminal ou até por engano. Quando isso acontece, o Git não limpa tudo automaticamente. Em vez disso, ele marca esses arquivos como ausentes e espera você tratar a remoção corretamente.

Veja como lidar com essa situação, passo a passo.

Passo 1: verifique arquivos ausentes

Rode isso na pasta do seu projeto:

git status

Se o Git disser que um arquivo foi deletado, significa que ele sumiu do seu sistema, mas a mudança ainda não foi colocada em stage.

Passo 2: coloque a exclusão em stage 

Para dizer ao Git para colocar todas as mudanças em stage (incluindo arquivos deletados), rode:

git add -A

• git add -A = coloca todas as mudanças em stage (novos, modificados, deletados).
• git add -u = coloca modificados + deletados, mas não novos.

Isso coloca todas as mudanças em stage: novos, modificados e deletados. Depois faça o commit:

git commit -m "Removed missing files"

Essa é a forma mais segura de limpar, porque captura tudo de uma vez.

Passo 3: faça push para o remoto 

Se estiver trabalhando com um repositório remoto, envie o commit:

git push origin <branch-name>

Substitua <branch-name> pela branch de trabalho, como main ou dev.

Passo 4: alternativa

Digamos que você deletou um monte de arquivos manualmente — por engano ou durante uma limpeza. O Git ainda acha que esses arquivos existem até você dizer o contrário.

Se você não quer remover um por um com git rm, há um jeito mais rápido de limpar.

Rode este comando no terminal:

git ls-files --deleted -z | xargs -0 git rm

O que ele faz:

• git ls-files --deleted lista todos os arquivos que o Git rastreava mas que agora estão ausentes.
• xargs -0 git rm passa esses nomes de arquivo para git rm e os remove do índice do Git.

Isso ajuda bastante quando você está num projeto grande e quer agilizar a limpeza.

Observação: recebi esta mensagem porque não há arquivos rastreados que estejam atualmente faltando no seu disco.

Remoção avançada de arquivos no Git

Agora que vimos o básico, vamos olhar situações mais avançadas, em que remover um arquivo do Git não é tão simples quanto rodar git rm. São casos que envolvem dados sensíveis ou limpeza cuidadosa de arquivos não rastreados.

Remover dados sensíveis do Git

Às vezes um arquivo com dados privados — como chaves de API ou senhas — é commitado por engano. Deletá-lo normalmente não resolve. Como o Git mantém um histórico completo, o arquivo continua existindo nos commits anteriores.

Para apagar de vez, você pode usar o comando git filter-repo: git filter-repo (recomendado)

É uma alternativa mais nova e melhor ao filter-branch. É mais rápido, seguro e fácil de usar.

Primeiro, instale (você vai precisar de Python e pip):

pip install git-filter-repo

Depois rode:

git filter-repo --path hide.txt --invert-paths

Isso remove o arquivo hide.txt de todos os commits do histórico do repositório.

Para confirmar, rode:

git log --all -- supersecrets.txt

Se o arquivo sumiu, adicione-o ao .gitignore para não voltar a ser rastreado:

echo hide.txt >> .gitignore

Se você trabalha em equipe, limpe o histórico reescrito e faça force push das mudanças:

git push origin --force --all

Depois avise o time. Eles vão precisar clonar novamente ou resetar as cópias locais para evitar erros.

Limpar arquivos não rastreados com git clean

Vamos por partes:

• Arquivos rastreados estão no histórico do Git. Para removê-los, use git rm e depois faça commit.
• Arquivos não rastreados não estão no Git. Eles podem se acumular e bagunçar o projeto.

Para deletar arquivos ou pastas não rastreados, use o git clean.

As opções mais úteis:

git clean -n     # Mostra quais arquivos não rastreados serão removidosgit clean -nd    # Mostra quais pastas não rastreadas serão removidasgit clean -fd    # Deleta todos os arquivos e pastas não rastreados. É destrutivo.

Aqui:

• -n significa só pré-visualizar.
• -f força a exclusão.
• -d inclui pastas na limpeza.

Atenção: o git clean não mexe em arquivos rastreados. Mas apaga qualquer coisa não rastreada, até arquivos que você queria manter. Então, sempre use -n antes para ver o que será removido.

Remoção de arquivos no GitHub e em ferramentas GUI

Até aqui usamos principalmente a linha de comando. Mas nem todo mundo trabalha assim — e tudo bem. Muitos devs usam ferramentas visuais ou trabalham direto no GitHub.

Vamos ver como a exclusão funciona na interface web do GitHub e em outras GUIs, e como isso se compara à linha de comando.

Excluir arquivos no site do GitHub

Se você está usando a interface do GitHub no navegador, dá para excluir arquivos sem o terminal.

Veja como funciona na interface de 2025:

1. Abra o arquivo que você quer excluir.
2. Clique nos três pontos no canto superior direito.
3. Escolha Delete file no menu.

O GitHub vai mostrar a caixa de mensagem de commit. Adicione uma mensagem curta, como:

Delete practice.py

Você também pode escrever uma descrição opcional.

Depois, escolha como salvar a mudança:

• Fazer commit diretamente na branch main
• Ou criar uma nova branch e abrir um pull request (recomendado para trabalho em equipe)

Clique em Commit changes e o GitHub vai remover o arquivo e salvar a exclusão como um commit — exatamente como o git rm faz na linha de comando.

Excluir arquivos com ferramentas GUI de Git

Se você usa uma GUI como GitHub Desktop, Sourcetree ou Tower, o processo também é simples:

1. Exclua o arquivo no explorador de arquivos ou dentro do app.
2. O app mostra a exclusão em “Changes” ou “File Status”.
3. Revise, coloque em stage e faça o commit.

Cada ferramenta tem uma cara diferente, mas o fluxo é parecido: você acompanha as mudanças visualmente e commita quando estiver pronto.

Boas práticas por plataforma

Um panorama rápido de como a exclusão funciona em diferentes plataformas — e quando cada uma é mais útil:

• GitHub (Web): bom para correções rápidas e atualizações pequenas. Evite para limpezas grandes ou arquivos sensíveis. 
• Ferramentas GUI: ótimas para o dia a dia. Fica fácil visualizar mudanças e commitar com segurança. 
• Linha de comando: mais flexível e poderosa. Melhor para tarefas avançadas, como edições em lote ou alterações de histórico. 

Boas práticas para remover arquivos no Git

Remover arquivos no Git parece simples, mas um passo em falso pode quebrar seu código. Aqui vão dicas práticas que eu uso para garantir exclusões seguras e controladas — especialmente em projetos compartilhados ou de longo prazo.

Sempre verifique antes de deletar

Antes de remover um arquivo, reserve um minuto para confirmar o que ele faz:

• Rode git status para ver se ele está em stage ou modificado.
• Use git log -- <filename> para ver o histórico de commits dele.

Esse check rápido já me salvou horas de retrabalho.

Faça commits atômicos

Commit atômico é um commit por mudança lógica.

Por exemplo, se vou deletar arquivos não usados, faço um commit só com essas exclusões, separado de edições de código.

Por que isso ajuda:

• Depurar fica mais fácil. Ferramentas como git bisect funcionam melhor com commits pequenos e focados.
• O histórico fica limpo e claro.
• Code reviews andam mais rápido.

Reescreva histórico com cuidado e em equipe

Reescrever histórico com ferramentas como git filter-repo afeta todo o time. Para evitar caos:

• Avise antes de reescrever branches compartilhadas.
• Use git push --force com cuidado — ele reescreve o histórico remoto.
• Peça para o time re-clonar ou resetar os repositórios locais depois.

Use --dry-run antes de comandos destrutivos

Antes de rodar um comando que deleta arquivos, sempre teste:

git clean -n

Isso mostra o que seria deletado sem apagar nada. Por que eu acho que você sempre deve fazer isso: 

• Evita remover arquivos que você queria manter.
• É um paraquedas de segurança, especialmente em projetos grandes onde um erro pode apagar logs ou arquivos gerados.

Combine git rm --cached com .gitignore

Se você comitou algo que não deveria estar no repositório (como um config ou logs), corrija em duas etapas:

1. Retire o arquivo do rastreamento:```git rm --cached <filename>

git rm --cached <filename>

Isso diz ao Git para parar de rastrear o arquivo, mas mantê-lo no seu computador.

1. Adicione ao .gitignore:

echo <filename> >> .gitignore

Por que isso ajuda:

• Mantém arquivos sensíveis ou locais (como .env, .log ou node_modules) fora do repositório.
• Evita poluir o histórico do Git.
• Futuros ajustes nesses arquivos não vão gerar mudanças no Git.

Casos de borda no Git: staging e pastas vazias

Às vezes a remoção não sai como esperado. Você pode colocar o arquivo errado em stage ou ter problemas com pastas vazias. 

Veja como eu lido com casos comuns.

Tirar um arquivo do stage sem perder suas mudanças

Digamos que rodei git add . e coloquei em stage um arquivo sem querer. Eu não quero perder minhas alterações — só quero tirá-lo do stage.

Para resolver, eu rodo:

git reset HEAD <filename>

Isso tira o arquivo do stage, mas mantém as edições.

Para confirmar, eu uso:

git status

Agora o arquivo deve aparecer como "modified" em vez de "staged".

Mantendo pastas vazias no repositório

Por padrão, o Git ignora pastas vazias. Se eu tentar commitar uma pasta sem arquivos, o Git vai pular.

Mas às vezes eu quero manter a pasta no repositório — para futuros logs ou uploads. O truque é adicionar um arquivo placeholder chamado .gitkeep.

Como fazer:

touch logs/.gitkeepgit add logs/.gitkeepgit commit -m "Keep logs folder in the repo"

Isso torna a pasta "não vazia", então o Git passa a rastreá-la.

Atenção: .gitkeep não é um recurso do Git — é uma convenção. Você pode usar outro nome, mas .gitkeep deixa claro para os outros qual é o propósito.

Solução de problemas ao remover arquivos no Git

Alguns problemas comuns que já enfrentei ao remover arquivos no Git — e como resolver.

O arquivo ainda aparece no repositório remoto

Você deletou o arquivo, fez o commit, mas ele continua no remoto. Talvez você esqueceu de fazer push.

Então, garanta que rodou:

git push origin <branch-name>

Confira também:

• Você está na branch correta?
• Seu commit realmente incluiu a exclusão do arquivo?

Problemas com submódulos

Submódulos são repositórios Git dentro de outros repositórios Git. Eles não se comportam como pastas normais.

Se você vai deletar arquivos dentro de um submódulo:

• Entre na pasta do submódulo
• Faça commit e push das mudanças de dentro do submódulo

Se você vai remover o submódulo inteiro:

• Delete a pasta do submódulo
• Remova as referências em .gitmodules e .git/config

Estado de HEAD destacado (detached HEAD)

No Git, o HEAD normalmente aponta para a branch atual. Mas às vezes ele aponta para um commit específico — isso é o detached HEAD.

Isso acontece se você:

• Faz checkout de um commit pelo hash
• Troca para uma tag
• Faz checkout de uma branch remota sem configurar rastreamento

Confira seu status:

git status

Se você vir:

HEAD detached at <commit-hash>

Você não está em uma branch, e quaisquer mudanças podem se perder quando você sair daí.

Como corrigir: 

Se você fez mudanças e quer mantê-las, rode:

git checkout -b <new-branch-name>

Isso coloca seu trabalho em uma nova branch e salva tudo.

Se você já commitou as mudanças e quer levá-las para outra branch depois, faça:

git checkout -b temp-branch          # from detached HEADgit checkout main                    # or another target branchgit merge temp-branch

Se você não fez mudanças e só quer sair do detached HEAD, rode:

git checkout <branch-name> 

Pronto. O HEAD foi religado à branch e tudo volta ao normal.

Erros de permissão ou de estado

Às vezes o Git não consegue deletar um arquivo — geralmente no Windows. Isso pode acontecer se:

• O arquivo está aberto em outro programa
• O Git não tem permissão para atualizá-lo

Como resolver:

• Feche os apps que estão usando o arquivo
• Reinicie o terminal como Administrador (no Windows)

Problemas em merge ou rebase

Se você vir erros como:

• you are not currently on a branch
• merge conflict

Provavelmente você está no meio de um merge ou rebase.

Para finalizar um rebase depois de resolver conflitos:

git rebase --continue

Para cancelar o rebase ou merge por completo:

git reset --merge

Isso restaura o repositório ao estado de antes do início do merge.

Quer descartar todas as mudanças locais e resetar o diretório de trabalho? 

Tente:

git restore .

Isso devolve todos os arquivos ao último estado commitado.

Considerações finais 

Ao remover arquivos no Git, é fácil se enrolar se você não estiver atento. Um pequeno deslize pode virar um problemão: código quebrado, trabalho perdido ou confusão no time. Por isso, vale a pena conferir duas vezes o que você está fazendo.

Use o comando certo para cada situação. Se não tiver certeza do que algo vai fazer, teste antes com um dry run. E, se estiver trabalhando com outras pessoas, garanta que todo mundo está alinhado.

O Git faz muito mais do que deletar arquivos. Você pode apagar branches, desfazer erros com reset e revert ou ver exatamente o que mudou com o git diff. Quanto mais você aprende, mais fluido fica seu fluxo de trabalho.

Vá passo a passo. É assim que você fica bom nisso.