Remover binários grandes do histórico do Git com git filter-repo

Objetivo

Reduzir o tamanho de um repositório cujo histórico contém binários grandes (saídas de build, mídia, dumps de banco de dados ou um segredo que precisa desaparecer), para que clones e fetches voltem a ser rápidos.

Pré-requisitos

git filter-repo instalado (a própria documentação do git-filter-branch o recomenda como alternativa e marca o filter-branch como não recomendado). Permissão para fazer force push de todas as branches e tags, e um meio de alcançar todos os colaboradores e sistemas de CI. Um período tranquilo em que ninguém faça push.

Passos

1. Meça primeiro: git count-objects -vH mostra o tamanho do pack; git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | sort -k3 -n | tail -20 lista os maiores blobs com seus caminhos. git filter-repo --analyze gera relatórios sobre caminhos e tamanhos de blobs sem modificar o repositório.
2. Decida o que sai: caminhos inteiros (--path build/ --invert-paths), blobs acima de um determinado tamanho (--strip-blobs-bigger-than 10M) ou IDs de blobs específicos. Mova os arquivos que ainda são necessários para o LFS ou para um armazenamento externo antes da reescrita.
3. Trabalhe num clone novo (git clone --mirror ou um clone comum). O manual informa que o filter-repo aborta quando executado num repositório que não seja um clone novo, para proteger um histórico que não exista em nenhum outro lugar.
4. Execute a reescrita, por exemplo git filter-repo --strip-blobs-bigger-than 10M --path assets/raw/ --invert-paths. Revise o resultado: git log --stat, a listagem dos maiores blobs de novo e um build a partir da árvore reescrita.
5. Anuncie a virada com uma data. Pause o CI e bloqueie os pushes.
6. Faça o push do resultado. O manual informa que o filter-repo remove o remote origin para incentivar o uso de um novo repositório; envie para esse novo remote e aposente o antigo, ou adicione origin de novo e execute git push --force --branches --tags --prune, como o manual mostra.
7. No servidor, expire os reflogs e execute a coleta de lixo, ou use a função de limpeza da plataforma de hospedagem; até lá, os objetos antigos continuam acessíveis e o tamanho não diminui.
8. Todos os colaboradores clonam de novo. Clones existentes que façam merge ou rebase de branches antigas vão enviar os objetos antigos diretamente de volta.

Resultado esperado

O tamanho do pack cai para o do conteúdo restante; os IDs de commit antigos deixam de ser resolvidos; os pull requests abertos foram rebaseados sobre as branches reescritas.

Limites e base de verificação

Uma reescrita é destrutiva e global: as assinaturas dos commits antigos não são transferidas para os reescritos (a assinatura cobre o conteúdo antigo), as referências em tickets e mensagens de commit apontam para IDs que não existem mais (o filter-repo pode criar replace refs e reescrever mensagens para atenuar isso) e os forks mantêm o histórico antigo. Um segredo removido ainda precisa ser rotacionado; podem existir cópias em outros lugares. Os passos seguem os manuais citados; nenhum tamanho ou duração é afirmado.

Decidir se uma reescrita é realmente necessária

Antes do passo 1, verifique qual das três condições se aplica: o servidor recusa ou limita o repositório (cota de tamanho ou limite de push), os objetos não podem existir em lugar nenhum (um segredo, um problema de licenciamento) ou o host não oferece suporte a partial clone. Se nenhuma se aplica e o motivo é o tempo de clone, configure o partial clone em vez disso: git clone --filter=blob:none ou --filter=blob:limit=1m dá a desenvolvedores e ao CI um clone rápido sem reescrever o histórico, sem invalidar pull requests e sem obrigar ninguém a clonar de novo; os objetos grandes permanecem no servidor, o que costuma ser aceitável. Reserve a reescrita para os três casos acima e, mesmo assim, rotacione primeiro qualquer segredo, pois a reescrita só remove as cópias que você controla.