Eliminar binarios grandes del historial de Git con git filter-repo

Objetivo

Reducir el tamaño de un repositorio cuyo historial contiene binarios grandes (artefactos de compilación, archivos multimedia, volcados de bases de datos o un secreto que debe desaparecer) para que los clones y los fetch vuelvan a ser rápidos.

Requisitos previos

git filter-repo instalado (la propia documentación de git-filter-branch lo recomienda como alternativa y desaconseja el uso de filter-branch). Permiso para hacer force-push de todas las ramas y etiquetas, y una forma de contactar con todos los colaboradores y sistemas de CI. Un periodo de calma en el que nadie haga push.

Pasos

1. Mida primero: git count-objects -vH muestra el tamaño del pack; git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | sort -k3 -n | tail -20 lista los blobs más grandes con sus rutas. git filter-repo --analyze genera informes sobre rutas y tamaños de blobs sin modificar el repositorio.
2. Decida qué se elimina: rutas completas (--path build/ --invert-paths), blobs por encima de un tamaño (--strip-blobs-bigger-than 10M) o ID de blobs concretos. Traslade a LFS o a un almacenamiento externo los archivos que todavía se necesiten antes de la reescritura.
3. Trabaje en un clon nuevo (git clone --mirror o un clon normal). El manual indica que filter-repo se detiene si se ejecuta en un repositorio que no es un clon nuevo, para proteger historial que no existe en ningún otro sitio.
4. Ejecute la reescritura, por ejemplo git filter-repo --strip-blobs-bigger-than 10M --path assets/raw/ --invert-paths. Revise el resultado: git log --stat, de nuevo el listado de los blobs más grandes y una compilación a partir del árbol reescrito.
5. Anuncie el cambio con una fecha. Pause la CI y bloquee los push.
6. Suba el resultado. El manual indica que filter-repo elimina el remoto origin para animar a los usuarios a pasarse a un repositorio nuevo; o bien se hace push a ese nuevo remoto y se retira el antiguo, o bien se vuelve a añadir origin y se ejecuta git push --force --branches --tags --prune, como muestra el manual.
7. En el servidor, expire los reflogs y ejecute la recolección de basura, o use la función de limpieza de la plataforma de alojamiento; hasta entonces los objetos antiguos siguen siendo accesibles y el tamaño no baja.
8. Todos los colaboradores vuelven a clonar. Los clones existentes que hagan merge o rebase de ramas antiguas volverán a subir de inmediato los objetos antiguos.

Resultado esperado

El tamaño del pack se reduce al del contenido restante; los ID de commit antiguos ya no se resuelven; las pull requests abiertas se han rebasado sobre las ramas reescritas.

Límites y base de verificación

Una reescritura es destructiva y global: las firmas de los commits antiguos no se trasladan a los reescritos (una firma cubre el contenido antiguo), las referencias en tickets y mensajes de commit apuntan a ID que ya no existen (filter-repo puede crear replace refs y reescribir mensajes para atenuarlo) y los forks conservan el historial antiguo. Un secreto eliminado debe rotarse igualmente, porque pueden existir copias en otros lugares. Los pasos siguen los manuales citados; no se afirma ningún tamaño ni duración.

Decidir si realmente hace falta una reescritura

Antes del paso 1, determine cuál de estas tres condiciones se cumple: el servidor rechaza o limita el repositorio (una cuota de tamaño o un límite de push), los objetos no deben existir en ningún sitio (un secreto, un problema de licencias) o el host no admite el clon parcial. Si no se aplica ninguna y el motivo es el tiempo de clonado, configure en su lugar el clon parcial: git clone --filter=blob:none o --filter=blob:limit=1m ofrece a desarrolladores y CI un clon rápido sin reescribir el historial, sin invalidar pull requests y sin obligar a nadie a volver a clonar; los objetos grandes permanecen en el servidor, lo cual suele ser aceptable. Reserve la reescritura para los tres casos anteriores y, aun así, rote primero cualquier secreto, ya que la reescritura solo elimina las copias que usted controla.