Supprimer de gros binaires de l'historique Git avec git filter-repo

Objectif

Réduire la taille d'un dépôt dont l'historique contient de gros binaires (résultats de build, médias, dumps de base de données, ou un secret qui doit disparaître), afin que les clones et les fetch redeviennent rapides.

Prérequis

git filter-repo installé (la documentation de git-filter-branch elle-même le recommande comme alternative et marque filter-branch comme déconseillé). La permission de forcer le push de chaque branche et de chaque tag, et un moyen de joindre chaque collaborateur et chaque système d'intégration continue. Une période calme pendant laquelle personne ne pousse.

Étapes

1. Mesurer d'abord : git count-objects -vH affiche la taille du pack ; git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | sort -k3 -n | tail -20 liste les plus gros blobs avec leurs chemins. git filter-repo --analyze écrit des rapports sur les chemins et les tailles de blob sans modifier le dépôt.
2. Décider ce qui part : des chemins entiers (--path build/ --invert-paths), des blobs au-delà d'une taille (--strip-blobs-bigger-than 10M), ou des ID de blob précis. Déplacer avant la réécriture les fichiers encore nécessaires vers LFS ou un stockage externe.
3. Travailler dans un clone neuf (git clone --mirror ou un clone simple). Le manuel indique que filter-repo s'interrompt lorsqu'il est exécuté dans un dépôt qui n'est pas un clone neuf, afin de protéger un historique qui n'existe nulle part ailleurs.
4. Lancer la réécriture, par exemple git filter-repo --strip-blobs-bigger-than 10M --path assets/raw/ --invert-paths. Contrôler le résultat : git log --stat, à nouveau le listage des plus gros blobs, et un build à partir de l'arborescence réécrite.
5. Annoncer la bascule avec une date. Mettre l'intégration continue en pause et bloquer les push.
6. Pousser le résultat. Le manuel indique que filter-repo supprime le remote origin afin d'orienter les personnes vers un nouveau dépôt ; soit pousser vers ce nouveau remote et retirer l'ancien dépôt, soit rajouter origin et exécuter git push --force --branches --tags --prune comme le montre le manuel.
7. Sur le serveur, expirer les reflogs et lancer le ramasse-miettes, ou utiliser la fonction de nettoyage de la plateforme d'hébergement ; jusque-là, les anciens objets restent accessibles et la taille ne diminue pas.
8. Chaque collaborateur reclone. Les clones existants qui fusionnent ou rebasent d'anciennes branches repousseront directement les anciens objets.

Résultat attendu

La taille du pack est réduite à celle du contenu restant ; les anciens ID de commit ne se résolvent plus ; les pull requests ouvertes ont été rebasées sur les branches réécrites.

Limites et base de vérification

Une réécriture est destructive et globale : les signatures des anciens commits ne se reportent pas sur les commits réécrits (une signature porte sur l'ancien contenu), les références dans les tickets et les messages de commit pointent vers des ID qui n'existent plus (filter-repo peut créer des refs de remplacement et réécrire les messages pour atténuer cela), et les forks conservent l'ancien historique. Un secret supprimé doit tout de même être renouvelé ; des copies peuvent exister ailleurs. Les étapes suivent les manuels cités en référence ; aucune taille ni durée n'est revendiquée.

Décider si une réécriture est vraiment nécessaire

Avant l'étape 1, déterminer laquelle des trois conditions s'applique : le serveur refuse ou limite le dépôt (un quota de taille ou une limite de push), les objets ne doivent exister nulle part (un secret, un problème de licence), ou l'hébergeur ne prend pas en charge le clone partiel. Si aucune ne s'applique et que le motif est le temps de clonage, configurer plutôt un clone partiel : git clone --filter=blob:none ou --filter=blob:limit=1m donne aux développeurs et à l'intégration continue un clone rapide sans réécrire l'historique, invalider les pull requests ni forcer qui que ce soit à recloner ; les gros objets restent sur le serveur, ce qui est généralement acceptable. Réserver la réécriture aux trois cas ci-dessus, et même alors renouveler tout secret en premier, car la réécriture ne supprime que les copies que l'on contrôle.