Sinopsis
git filter-repo --path <path> [--invert-paths]
git filter-repo --replace-text <file>
git filter-repo --strip-blobs-bigger-than 10MDescripción
git filter-repo es una herramienta de tercera parte (recomendada por el proyecto Git sobre el deprecado git filter-branch) para reescrituras a gran escala del historial: eliminar archivos, cambiar autores, eliminar branches, etc. Es órdenes de magnitud más rápida que filter-branch y más segura por defecto.
Usos comunes incluyen quitar archivos sensibles del historial, fusionar repos, y dividir un subdirectorio en su propio repo. Siempre opera sobre un clon fresco como protección, ya que cambia los SHAs de todos los commits.
En el uso diario, este comando se integra estrechamente con alias de shell, plugins de editor e integración continua. Los usuarios avanzados a menudo añaden alias que combinan los flags que siempre pasan. El formato de salida puede personalizarse vía configuración de Git. Cuando algo sale mal, ejecuta el comando con GIT_TRACE=1 para revelar las llamadas plumbing subyacentes.
Entender cómo este comando interactúa con el resto del modelo de datos de Git rinde dividendos. Cada comando opera sobre algún subconjunto de las piezas (objetos, index, refs, árbol de trabajo), y saber cuáles toca ayuda a predecir resultados y a recuperarse de errores.
Opciones comunes
| Opción | Descripción |
|---|---|
--path <p> | Keep only the specified path. |
--invert-paths | Inverse: remove the specified paths. |
--path-glob <g> | Use a glob pattern. |
--replace-text <file> | Replace strings throughout history. |
--strip-blobs-bigger-than <size> | Drop large blobs. |
--mailmap <file> | Rewrite author/committer info. |
--analyze | Produce a report on repo size before rewriting. |
--force | Override the fresh-clone safety check. |
Ejemplos
git filter-repo --analyze
# Inspect what's eating space
git filter-repo --path docs/ --invert-paths
# Remove docs/ from all history
git filter-repo --strip-blobs-bigger-than 50M
# Purge any file over 50 MB
echo 'API_KEY==>REDACTED' > replacements.txt
git filter-repo --replace-text replacements.txt
# Scrub a leaked secretErrores comunes
Running filter-repo in your live repo without a backup risks losing data. Always clone fresh. After rewriting, force-push and have collaborators re-clone — anyone with old SHAs will get conflicts. The tool removes origin by default to prevent accidental pushes; re-add it deliberately.
Comandos relacionados
git filter-branch (deprecated), git gc, git reflog, git push --force-with-lease