Git LFS

Wenn du einen Commit auscheckst, der Git LFS Pointers enthält, werden diese mit Dateien aus deinem lokalen Git LFS-Cache ersetzt oder vom Git LFS-Remote-Speicher heruntergeladen.

Git LFS ist nahtlos: In deiner Arbeitskopie siehst du nur deinen tatsächlichen Dateiinhalt. Aus diesem Grund kannst du Git LFS nutzen, ohne deinen bestehenden Git-Workflow zu ändern. Du arbeitest einfach wie immer mit den Befehlen git checkout, edit, git add und git commit. git clone und git pull werden erheblich schneller ausgeführt, wenn du nur die Versionen großer Dateien herunterlädst, die von den Commits referenziert werden, die du tatsächlich auscheckst, anstatt jeder Version der Datei, die jemals existiert hat.

Für Git LFS brauchst du einen Git-LFS-fähigen Host, wie etwa Bitbucket Cloud oder Bitbucket Data Center. Repository-Benutzer müssen den Befehlszeilen-Client für Git LFS installiert haben oder einen Git-LFS-fähigen GUI-Client wie SourceTree verwenden. Übrigens: Steve Streeting, der Atlassian-Entwickler von SourceTree, beteiligt sich auch intensiv am Git-LFS-Projekt. Daher sind SourceTree und Git LFS gut miteinander kompatibel.

1. Es gibt drei einfache Möglichkeiten zur Installation von Git LFS:

a. Installiere es mit deinem bevorzugten Paketmanager. git-lfs-Pakete sind verfügbar für Homebrew, MacPorts, dnf und packagecloud.

b. Lade Git LFS von der Projekt-Webseite herunter und installiere es.

c. Installiere SourceTree, einen kostenlosen GUI-Client für Git, der zusammen mit Git LFS erhältlich ist.

2. Führe nach dem Initialisieren von Git LFS den Befehl "git lfs install" aus (wenn du SourceTree installiert hast, kannst du diesen Schritt überspringen):

Du musst git lfs install nur einmal ausführen. Sobald Git LFS für dein System initialisiert ist, wird es automatisch geladen, wenn du ein Repository mit Git LFS-Inhalten klonst.

Wenn ein neues Repository mit Git LFS kompatibel sein soll, musst du nach dem Erstellen des Repositorys "git lfs install" ausführen.

Hiermit wird ein spezieller pre-push-Git Hook in deinem Repository installiert, der Git LFS-Dateien an den Server überträgt, wenn du git push ausführst.

Git LFS wird automatisch für alle Bitbucket Cloud-Repositorys aktiviert. Für Bitbucket Data Center musst du Git LFS in den Einstellungen deines Repositorys aktivieren:

Sobald Git LFS für dein Repository initialisiert ist, kannst du mit git lfs track festlegen, welche Dateien verfolgt werden sollen.

Nachdem Git LFS installiert ist, kannst du Git-LFS-Repositorys ganz normal mit git clone klonen. Am Ende des Klonprozesses wird Git den Standard-Branch auschecken (normalerweise den main) und alle Git-LFS-Dateien, die zum Abschluss des Checkout-Prozesses benötigt werden, werden automatisch für dich heruntergeladen. Ein Beispiel:

In diesem Repository befinden sich vier PNGs, die von Git LFS verfolgt werden. Beim Ausführen von "git clone", werden Git LFS-Dateien einzeln nacheinander heruntergeladen, während Pointer-Dateien aus deinem Repository ausgecheckt werden.

Wenn du ein Repository mit einer großen Anzahl von Dateien klonst, bietet der Befehl git lfs clone eine deutlich bessere Leistung:

Anstatt die Git LFS-Dateien einzeln herunterzuladen, wird beim Befehl git lfs clone gewartet, bis der Checkout abgeschlossen ist, und anschließend werden alle benötigten Git LFS-Dateien im Batch heruntergeladen. Hierbei werden parallelisierte Downloads genutzt und die Anzahl der ausgelösten HTTP-Anfragen und Prozesse sinkt drastisch (dies ist insbesondere zur Leistungsverbesserung in Windows von Bedeutung).

Genau wie beim Klonen kannst du mit einem normalen git pull-Befehl einen Pull von einem Git LFS-Repository durchführen. Alle benötigten Git LFS-Dateien werden im Rahmen des automatischen Checkout-Prozesses heruntergeladen, sobald der Pull abgeschlossen ist.

Zum Abrufen von Git LFS-Inhalten werden keine expliziten Befehle benötigt. Sollte der Checkout jedoch unerwartet fehlschlagen, kannst du für den aktuellen Commit fehlende Git LFS-Inhalte mit git lfs pull herunterladen:

Wie git lfs clone lädt git lfs pull deine Git LFS-Dateien im Batch herunter. Wenn du weißt, dass sich seit dem letzten Pull ein große Anzahl an Dateien geändert hat, solltest du ggf. den automatischen Git LFS-Download während des Checkouts deaktivieren und dann deinen Git LFS-Inhalt mit einem expliziten git lfs pull-Befehl im Batch herunterladen. Hierzu setzt du dein Git config mit der Option -c außer Kraft, wenn du git pull ausführst:

Da die Eingabe hiervon recht mühselig ist, kannst du zum Durchführen eines Batch-Downloads und eines Git LFS-Pulls einen einfachen Git alias erstellen:

Dies verbessert die Leistung erheblich, wenn eine große Anzahl an Git LFS-Dateien heruntergeladen werden muss (auch hier insbesondere bei Windows).

Wenn du deinem Repository einen neuen Dateityp großer Dateien hinzufügst, musst du Git LFS mit dem Befehl git lfs track anweisen, diese nach einem bestimmten Muster zu verfolgen:

Beachte, dass die Anführungszeichen um "*.ogg" wichtig sind. Wenn du sie vergisst, wird die Wildcard von der Shell erweitert und für jede .ogg-Datei in deinem aktuellen Verzeichnis werden eigene Einträge erstellt.

Die von Git LFS unterstützten Muster sind dieselben, die auch von .gitignore unterstützt werden, zum Beispiel:

Diese Muster hängen von dem Verzeichnis ab, in dem du den Befehl git lfs track ausgeführt hast. Der Einfachheit halber solltest du git lfs track von der Root deines Repositorys aus ausführen. Beachte, dass Git LFS keine negativen Muster unterstützt, auch wenn dies bei .gitignore der Fall ist.

Nach dem Ausführen von git lfs track wirst du in dem Verzeichnis, von dem aus du den Befehl ausgeführt hast, eine neue Datei namens .gitattributes finden. .gitattributes ist ein Git-Mechanismus zum Binden spezieller Verhaltensmuster an bestimmte Dateimuster. Git LFS erstellt oder aktualisiert .gitattributes-Dateien automatisch, um die Muster verfolgter Dateien an den Git LFS-Filter zu binden. Änderungen an der .gitattributes-Datei musst du jedoch selbst an dein Repository committen:

Zur leichteren Pflege ist es sinnvoll, alle Git LFS-Muster in einer einzigen .gitattributes-Datei zu sammeln, indem du git lfs track immer von der Root deines Repositorys aus ausführst. Du kannst dir jedoch eine Liste aller Muster, die derzeit von Git LFS verfolgt werden (und die .gitattributes-Dateien, in denen sie definiert sind), anzeigen lassen, indem du git lfs track ohne zusätzliche Argumente ausführst:

Du kannst die Verfolgung eines bestimmten Musters durch Git LFS beenden, indem du einfach die entsprechende Zeile aus deiner .gitattributes-Datei entfernst oder den Befehl git lfs untrack ausführst:

Nach dem Ausführen von git lfs untrack musst du die Änderungen an .gitattributes manuell committen.

Du kannst zu einem Repository mit Git LFS-Inhalten ganz normal committen und pushen. Wenn du Änderungen an Dateien committet hast, die von Git LFS verfolgt werden, wird dir eine zusätzliche Ausgabe von git push angezeigt, da die Git LFS-Inhalte zum Server übertragen werden:

Wenn die Übertragung der LFS-Dateien aus irgendeinem Grund fehlschlägt, wird der Push abgebrochen und du kannst es einfach erneut versuchen. Wie Git ist auch der Git-LFS-Speicher inhaltsadressiert: Zusammen mit den Inhalten wird ein Schlüssel abgespeichert, der ein SHA-256-Hash des Inhalts selbst ist. Ein erneuter Übertragungsversuch von Git-LFS-Dateien an den Server ist also immer sicher, da du die Inhalte einer Git-LFS-Datei nicht versehentlich mit der falschen Version überschreiben kannst.

Zur Migration eines Git LFS-Repositorys von einem Hosting-Anbieter zu einem andren kannst du git lfs fetch und git lfs push zusammen mit der Option --all kombinieren.

So verschiebst du z. B. alle Git- and Git-LFS-Repositorys von einem Remote namens github zu einem Remote namens bitbucket 😉 :

Git LFS lädt normalerweise nur die Dateien herunter, die für die tatsächlich lokal ausgecheckten Commits benötigst. Du kannst jedoch Git LFS mit git lfs fetch --recent zwingen, zusätzliche Inhalte für andere kürzlich modifizierte Branches herunterzuladen:

Dies ist hilfreich zum Herunterladen von neuen Git LFS-Inhalten in Batches, während du Mittagspause machst, oder wenn du Arbeitsresultate deiner Teamkollegen überprüfen möchtest und die Inhalte später aufgrund eingeschränkter Internetverbindung nicht mehr herunterladen kannst. Es ist beispielsweise sinnvoll, git lfs fetch --recent auszuführen, bevor du in ein Flugzeug steigst!

Git LFS betrachtet alle Branches oder Tags, die einen Commit enthalten, der neuer als sieben Tage ist als aktuell. Du kannst die Anzahl der Tage, für die Branches und Tags als aktuell gelten sollen, konfigurieren, indem du die Eigenschaft lfs.fetchrecentrefsdays entsprechend festlegst:

In den Standardeinstellungen wird git lfs fetch --recent nur Git LFS-Inhalte für den Commit an der Spitze des letzten Branch oder Tags herunterladen.

Du kannst jedoch Git LFS mit der Eigenschaft lfs.fetchrecentcommitsdays konfigurieren, damit Inhalte älterer Commits auf aktuellen Branches und Tags ebenfalls heruntergeladen werden.

Verwende diese Einstellung mit Bedacht: Wenn sich deine Branches mit einer hohen Geschwindigkeit weiterentwickeln, kann dies dazu führen, dass eine riesige Datenmenge heruntergeladen wird. Sie kann jedoch nützlich sein, wenn du interstitielle Änderungen in einem Branch überprüfen, Commits gezielt aus verschiedenen Branches auswählen oder den Verlauf umschreiben möchtest.

Wie in Verschieben eines Git LFS-Repositorys zwischen Hosts erläutert, kannst du auch alle Git LFS-Inhalte deines Repositorys mit git lfs fetch --all abrufen:

Mit dem Befehl git lfs prune kannst du Dateien von deinem lokalen Git LFS-Cache löschen:

Hiermit werden alle lokalen Git LFS-Dateien gelöscht, die als alt angesehen werden. Dies sind alle Dateien, für die keine Referenzen vorhanden sind in:

• Dem aktuell ausgecheckten Commit
• Einem Commit, der noch nicht gepusht wurde (zu origin oder entsprechend den Einstellungen von lfs.pruneremotetocheck)
• Einem aktuellen Commit

In den Standardeinstellungen ist ein aktueller Commit ein Commit, der in den letzten zehn Tagen erstellt wurde. Zur Berechnung wird Folgendes addiert:

• Der Wert der Eigenschaft lfs.fetchrecentrefsdays, die wir in Abrufen zusätzlicher Git LFS-Verlaufsinhalte behandelt haben (und die standardmäßig auf sieben gesetzt ist), und
• der Wert der Eigenschaft lfs.pruneoffsetdays (die standardmäßig auf drei gesetzt ist)

Du kannst für die Option "prune" ein zeitlich versetztes Löschen konfigurieren, um Git-LFS-Inhalte über einen längeren Zeitraum zu speichern.

Im Gegensatz zur integrierten Speicherbereinigung in Git werden Git-LFS-Inhalte mit "prune" nicht automatisch gelöscht. Daher solltest du git lfs prune regelmäßig nutzen, damit dein lokales Repository nicht zu groß wird.

Du kannst die Auswirkungen eines "prune"-Löschvorgangs mit git lfs prune --dry-run testen:

Und mit git lfs prune --verbose --dry-run testest du, welche Git-LFS-Objekte genau mit "prune" gelöscht werden:

Die im Modus --verbose ausgegebenen Hexadezimal-Strings sind SHA-256-Hashes (auch Objekt-IDs oder OIDs genannt) der mit "prune" zu löschenden Git-LFS-Objekte. Im Abschnitt Pfade oder Commits finden, die auf ein Git-LFS-Objekt verweisen erklären wir dir genauer, wie du mehr über die mit "prune" zu löschenden Objekte erfährst.

Um ganz sicherzugehen, kannst du mit --verify-remote überprüfen, ob deine Git-LFS-Objekte in den Git-LFS-Speicher kopiert worden sind, bevor du diese Objekte mit der Option "prune" löschst:

Zwar wird das Löschen mit "prune" dadurch verlangsamt, doch du kannst dich darauf verlassen, dass alle so gelöschten Objekt vom Server wiederherstellbar sind. Wenn du die Option --verify-remote für dein System dauerhaft aktivieren willst, kannst du die Eigenschaft lfs.pruneverifyremotealways global konfigurieren:

Alternativ kannst du die Remote-Überprüfung nur für das Repository in diesem Zusammenhang aktivieren, indem du aus dem Befehl oben die Option --global entfernst.

Mit dem Befehlszeilen-Client von Git LFS können Dateien mit der Option "prune" nicht vom Server gelöscht werden. Das Löschen ist daher vom Hostinganbieter abhängig.

In Bitbucket Cloud kannst du Git-LFS-Dateien über Repository Settings (Repository-Einstellungen) > Git LFS (Git LFS) ansehen und löschen.

Beachte, dass jede Git-LFS-Datei mit einem SHA-256-OID indiziert ist. Die Pfade, die auf die jeweilige Datei verweisen, sind in der Benutzeroberfläche nicht sichtbar. Da mehrere Commits möglich sind, könnte es auch viele verschiedene Pfade geben, die auf ein bestimmtes Objekt verweisen, daher würde es sehr lange dauern, diese Pfade aufzurufen.

Zur Bestimmung des tatsächlichen Inhalts einer Git LFS-Datei hast du drei Optionen:

• Sieh dir die Dateivoransicht und den Dateityp in der linken Spalte der Git-LFS-UI von Bitbucket an.
• Lade die Datei herunter, indem du in Bitbucket den Link in der rechten Spalte der Git-LFS-UI-Suche für Commits, die auf den SHA-256-OID des Git-LFS-Objekts verweisen, verwendest. Darauf gehen wir im nächsten Abschnitt genauer ein.

Wenn du in Git LFS einen SHA-256-OID hast, kannst du mit git log --all -p -S bestimmen, welche Commits auf diesen OID verweisen:

Dieser git log-Befehl generiert einen Patch (-p) von Commits aller Branches (--all), bei denen eine Zeile hinzugefügt oder entfernt wurde (-S), die den angegebenen String enthält (eine Git LFS SHA-256 OID).

Der Patch zeigt Commit und Pfad zum LFS-Objekt an und auch, wer ihn hinzugefügt hat und wann er committet wurde. Wenn du den Commit einfach auscheckst, lädt Git LFS die Datei wenn nötig herunter und legt sie in deiner Arbeitskopie ab.

Wenn du vermutest, dass ein spezielles Git-LFS-Objekt in deinem aktuellen HEAD oder in einem bestimmten Branch ist, kannst du mit git grep den darauf verweisenden Dateipfad ausfindig machen:

Du kannst HEAD oder power-ups durch einen beliebigen Ref, Commit oder Baum ersetzen, der das Git-LFS-Objekt beinhaltet.

Es kann jedoch auch sein, dass du für einen bestimmten Commit nur einen Teil der verfügbaren Git-LFS-Inhalte herunterladen willst. Wenn du z. B. CI-Builds für Unit-Tests konfigurierst, brauchst du nur den Quellcode. Sehr große Dateien, die zur Codeerstellung nicht nötig sind, wirst du dann ausschließen wollen.

Mit git lfs fetch -X (oder --exclude) kannst du ein Muster oder ein Unterverzeichnis ausschließen:

Andernfalls solltest du nur ein bestimmtes Muster oder ein Unterverzeichnis einschließen. Ein Tontechniker könnte z. B. nur ogg- und wav-Dateien mithilfe von git lfs fetch -I (oder --include) abrufen:

Wenn du include- und exclude-Anweisungen zum Einschließen bzw. Ausschließen kombinierst, werden nur die Dateien abgerufen, die dem include-Muster und zugleich nicht dem exclude-Muster entsprechen. Zum Beispiel kannst du alle Dateien außer GIFs in deinem Assets-Verzeichnis abrufen. Das geht so:

Auf exclude- und include-Anweisungen sind dieselben Muster anwendbar wie auf git lfs track und .gitignore. Diese Muster kannst du mit den Konfigurationseigenschaften lfs.fetchinclude und lfs.fetchexclude für ein bestimmtes Repository als dauerhaft definieren:

Diese Einstellungen kannst du durch Anhängen der Option --global auch auf jedes andere Repository in deinem System anwenden.

Leider gibt es keine einfache Möglichkeit, binäre Merge-Konflikte zu lösen. Mit einer Git-LFS-Dateisperre kannst du Dateien nach Erweiterung oder nach Dateinamen sperren und verhindern, dass Binärdateien während einem Merge überschrieben werden.

Um die Dateisperrfunktion von LFS nutzen zu können, musst du Git zunächst mitteilen, welche Dateitypen gesperrt werden sollen. Im Beispiel unten wird das Flag --lockable an den Befehl git lfs track angehängt, um PSD-Dateien in LFS zu speichern und sie als sperrbar zu kennzeichnen.

Dann füge Folgendes zu deiner .gitattributes-Datei hinzu:

Wenn du Änderungen an einer LFS-Datei vorbereitest, verwendest du den Sperrbefehl, um die Datei auf deinem Git-Server als gesperrt zu registrieren.

Sobald du die Dateisperre nicht mehr benötigst, kannst du sie mit dem Befehl git lfs unlock entfernen.

Git-LFS-Dateisperren können, ähnlich wie bei git push, mithilfe eines --force-Flags außer Kraft gesetzt werden. Verwende das Flag --force nicht, wenn du dir nicht absolut sicher bist, dass du weißt, was du tust.