Grosse Binärdateien mit git filter-repo aus der Git-Historie entfernen

Ziel

Die Grösse eines Repositorys reduzieren, dessen Historie grosse Binärdateien enthält (Build-Ausgaben, Medien, Datenbank-Dumps, oder ein Geheimnis, das verschwinden muss), damit Klonen und Fetchen wieder schnell werden.

Voraussetzungen

git filter-repo installiert (die git-filter-branch-Dokumentation selbst empfiehlt es als Alternative und kennzeichnet filter-branch als nicht empfohlen). Die Berechtigung, jeden Branch und Tag per Force-Push zu übertragen, sowie eine Möglichkeit, jede mitwirkende Person und jedes CI-System zu erreichen. Eine ruhige Phase, in der niemand pusht.

Schritte

1. Zuerst messen: git count-objects -vH zeigt die Pack-Grösse; git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | sort -k3 -n | tail -20 listet die grössten Blobs mit ihren Pfaden auf. git filter-repo --analyze schreibt Berichte zu Pfaden und Blob-Grössen, ohne das Repository zu verändern.
2. Entscheiden, was verschwindet: ganze Pfade (--path build/ --invert-paths), Blobs oberhalb einer Grösse (--strip-blobs-bigger-than 10M), oder bestimmte Blob-IDs. Noch benötigte Dateien vor dem Umschreiben nach LFS oder in einen externen Speicher verschieben.
3. In einem frischen Klon arbeiten (git clone --mirror oder ein einfacher Klon). Das Handbuch besagt, dass filter-repo abbricht, wenn es in einem Repository ausgeführt wird, das kein frischer Klon ist, um Historie zu schützen, die sonst nirgendwo existiert.
4. Das Umschreiben ausführen, zum Beispiel git filter-repo --strip-blobs-bigger-than 10M --path assets/raw/ --invert-paths. Das Ergebnis prüfen: git log --stat, erneut die Liste der grössten Blobs, sowie ein Build aus dem umgeschriebenen Baum.
5. Die Umstellung mit einem Datum ankündigen. CI pausieren und Pushes blockieren.
6. Das Ergebnis pushen. Das Handbuch besagt, dass filter-repo das Remote origin entfernt, um Nutzende zu einem neuen Repository zu bewegen; entweder zu diesem neuen Remote pushen und das alte ausser Betrieb nehmen, oder origin wieder hinzufügen und git push --force --branches --tags --prune ausführen, wie es das Handbuch zeigt.
7. Auf dem Server Reflogs verfallen lassen und Garbage Collection ausführen, oder die Aufräumfunktion der Hosting-Plattform nutzen; bis dahin bleiben die alten Objekte erreichbar, und die Grösse sinkt nicht.
8. Jede mitwirkende Person klont neu. Bestehende Klone, die alte Branches mergen oder rebasen, pushen die alten Objekte direkt zurück.

Erwartetes Ergebnis

Die Pack-Grösse ist auf die Grösse des verbleibenden Inhalts gesunken; alte Commit-IDs lösen sich nicht mehr auf; offene Pull Requests wurden auf die umgeschriebenen Branches rebast.

Grenzen und Prüfbasis

Ein Umschreiben ist destruktiv und global: Signaturen an den alten Commits übertragen sich nicht auf die umgeschriebenen (eine Signatur deckt den alten Inhalt ab), Verweise in Tickets und Commit-Nachrichten zeigen auf IDs, die nicht mehr existieren (filter-repo kann Replace-Refs und Nachrichtenumschreibungen erstellen, um das abzufedern), und Forks behalten die alte Historie. Ein entferntes Geheimnis muss trotzdem rotiert werden; Kopien können anderswo existieren. Die Schritte folgen den zitierten Handbüchern; es werden keine Grössen oder Dauern behauptet.

Entscheiden, ob ein Umschreiben überhaupt nötig ist

Vor Schritt 1 entscheiden, welche von drei Bedingungen zutrifft: Der Server weist das Repository zurück oder drosselt es (eine Grössenquote oder ein Push-Limit), die Objekte dürfen nirgendwo mehr existieren (ein Geheimnis, ein Lizenzproblem), oder der Host unterstützt keinen Partial Clone. Trifft nichts davon zu und liegt das Motiv bei der Klonzeit, stattdessen Partial Clone konfigurieren: git clone --filter=blob:none oder --filter=blob:limit=1m gibt Entwickelnden und der CI einen schnellen Klon, ohne die Historie umzuschreiben, Pull Requests ungültig zu machen oder irgendjemanden zum Neuklonen zu zwingen; die grossen Objekte bleiben auf dem Server, was meist akzeptabel ist. Das Umschreiben für die drei oben genannten Fälle reservieren, und selbst dann zuerst jedes Geheimnis rotieren, da das Umschreiben nur die selbst kontrollierten Kopien entfernt.