git filter-branch

Patches e reescrita

Reescreve o histórico com filtros (obsoleto — use git filter-repo)

O comando 'git filter-branch' reescreve cada commit de um branch passando por filtros — por exemplo para remover um arquivo de todo o histórico. É lento, fácil de usar errado e oficialmente desaconselhado: o próprio Git mostra um aviso e recomenda git filter-repo. Como toda reescrita, dá um novo hash a cada commit, então todos precisam clonar de novo ou redefinir.

Sinopse

git filter-branch [--index-filter <cmd>] [--tree-filter <cmd>] [--msg-filter <cmd>] [--] <rev-list>
[ ] opcional| ou<arg> valor a substituir... repetível--flag opção

Exemplos

Remover um arquivo em todo lugar

git filter-branch --index-filter 'git rm --cached --ignore-unmatch .env' HEAD

O jeito antigo e lento.

O jeito recomendado

git filter-repo --path .env --invert-paths

git filter-repo (ferramenta à parte) faz isso rápido e com segurança.

Exemplos de fluxos de trabalho

1
Rotate the secret

Primeiro, torná-la inútil

2
git filter-repo --path config/secret.yml --invert-paths

Removê-la do histórico

3
git push --force --all

Substituir o histórico remoto

Solução de problemas

Não é possível criar um novo backup

Causa: refs/original existe de uma execução anterior

Apague-o (git update-ref -d refs/original/refs/heads/main) ou use -f

Dicas e armadilhas

Boas práticas

  • ✓Use git filter-repo no lugar.
  • ✓Faça backup do repositório antes de qualquer reescrita.

Erros comuns

  • ✗Reescrever histórico compartilhado sem avisar o time.
  • ✗Achar que uma reescrita torna seguro um segredo vazado — troque o segredo.

Perguntas frequentes

A:

É muito lento e tem muitas armadilhas que corrompem a reescrita em silêncio; o filter-repo resolve as duas coisas.