Por qué filter-repo

git filter-repo es el reemplazo moderno del obsoleto git filter-branch. Es dramáticamente más rápido — a veces 100x — más seguro por defecto, y proporciona las operaciones de alto nivel que la cirugía de historia realmente necesita: eliminar archivos, renombrar rutas, eliminar autores, dividir subdirectorios y cambiar emails en todos los commits.

Instalación

filter-repo no viene incluido con Git pero está ampliamente empaquetado. En macOS: brew install git-filter-repo. En Debian/Ubuntu: apt install git-filter-repo.

Eliminar un archivo de toda la historia

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

Esto reescribe cada commit que tocó secrets.env para omitir el archivo, luego poda los objetos huérfanos. Haz force-push del resultado y rota cualquier credencial filtrada inmediatamente.

Extraer un subdirectorio como nuevo repo

git clone --no-local original/ extracted/
cd extracted
git filter-repo --subdirectory-filter packages/foo

Renombrar rutas

git filter-repo --path-rename old/dir/:new/dir/

Actualizar emails de autor

cat > mailmap.txt <<'EOF'
Jane Doe <[email protected]> <[email protected]>
EOF
git filter-repo --mailmap mailmap.txt

Características de seguridad

filter-repo se niega a ejecutarse en un clone no fresco por defecto. Anula solo cuando entiendas las implicaciones:

git filter-repo --force

Errores comunes

Ejecutar en tu único clone con --force y sin backup. Siempre clona primero. Olvidar que filter-repo elimina el remote original para prevenir pushes accidentales — vuelve a añadirlo explícitamente.

Rendimiento

filter-repo hace streaming vía git fast-export/fast-import. Para repos muy grandes, ejecuta en un SSD rápido y aumenta core.bigFileThreshold si tienes problemas de memoria.