Git LFS: Pointer-Dateien, Smudge-Filter und wann man es nicht einsetzen sollte

Worum es geht

Git LFS ist eine Git-Erweiterung, die – in den Worten des Projekts – grosse Dateien wie Audiosamples, Videos, Datensätze und Grafiken innerhalb von Git durch Text-Pointer ersetzt, während die Inhalte auf einem entfernten Server gespeichert werden. Die Spezifikation definiert den Pointer: einige Key-Value-Zeilen mit version https://git-lfs.github.com/spec/v1, oid sha256:<hash> und size <bytes>. Das Werkzeug klinkt sich über Gits Clean- und Smudge-Filter ein, einmalig installiert mit git lfs install; git lfs track "*.psd" schreibt die Filterattribute in .gitattributes. Lokal liegen die tatsächlichen Inhalte unter .git/lfs/objects/, aufgeteilt nach den ersten Hash-Zeichen, und werden getrennt vom normalen Push und Fetch mit dem LFS-Server ausgetauscht.

Warum es wichtig ist

Jede Version einer Binärdatei bleibt für immer in der gewöhnlichen Git-Historie und wird bei jedem Klon heruntergeladen. Mit LFS enthält die Historie nur Pointer, und ein Klon ruft die Inhalte für den ausgecheckten Commit ab. Der Preis dafür ist ein zweites System: ein LFS-Endpoint mit eigener Authentifizierung sowie eigenen Bandbreiten- und Speicherkontingenten, ein Client, der auf jeder Maschine und jedem CI-Runner installiert sein muss, und Pointer, die überall dort als dreizeilige Textdateien auftauchen, wo der Client fehlt.

So wird es angewendet

• Vor dem ersten grossen Commit per Muster tracken; die Projektseite weist darauf hin, dass Tracking Dateien, die bereits in der Historie sind, nicht umwandelt – dafür ist git lfs migrate nötig.
• .gitattributes mit den LFS-Zeilen committen, damit sich alle Klone darüber einig sind, welche Pfade Pointer sind.
• Den Client in CI-Images installieren und git lfs pull (oder das LFS-fähige Checkout des Hosts) dort verwenden, wo Builds die Inhalte benötigen.
• Speicher und Bandbreite nach den Konditionen des Hosts einplanen; prüfen, wie nicht mehr referenzierte Objekte gezählt und bereinigt werden.
• Nicht für kleine, selten geänderte Dateien verwenden; ein eingecheckter Icon-Satz benötigt keinen zweiten Server.
• Nicht für Build-Ausgaben, Abhängigkeits-Archive oder Modellgewichte verwenden, die bereits von einer Paketregistry oder einem Objektspeicher versioniert werden; eine URL plus Prüfsumme im Repository ist einfacher.
• Nicht verwenden, wenn Klone ohne Netzwerkzugriff auf den LFS-Endpoint funktionieren müssen oder über Werkzeuge laufen, die den Smudge-Filter nicht ausführen.
• Nicht für Text verwenden, der lediglich zufällig gross ist (generiertes JSON, Fixtures); Git komprimiert Text gut per Delta, und eine LFS-getrackte Datei wird nur als ihr Pointer gedifft.

Stolpersteine

Ein Push von einer Maschine ohne LFS-Client (also ohne dessen Pre-push-Hook) sendet Pointer, deren Objekte den Server nie erreichen, und jeder andere Klon stellt dann beim Abrufversuch fest, dass diese Objekte fehlen. Fork- und Mirror-Workflows müssen LFS-Objekte ebenfalls kopieren. LFS später wieder zu entfernen bedeutet, die Historie erneut umzuschreiben.