Git LFS

Wanneer je een commit uitcheckt die Git LFS-pointers bevat, worden deze vervangen door bestanden uit je lokale Git LFS-cache of gedownload uit de externe Git LFS-store.

Git LFS is naadloos: in je werkkopie zie je alleen de daadwerkelijke bestandsinhoud. Dit betekent dat je Git LFS kunt gebruiken zonder je bestaande Git-workflow te wijzigen: je hoeft alleen maar git checkout, edit, git add en git commit te gebruiken, zoals gewoonlijk. De bewerkingen git clone en git pull zullen aanzienlijk sneller zijn omdat je alleen de versies downloadt van grote bestanden waarnaar wordt verwezen door commits die je daadwerkelijk bekijkt, in plaats van elke versie van het bestand die ooit bestond.

Om Git LFS te gebruiken, heb je een Git LFS-aware host nodig, zoals Bitbucket Cloud of Bitbucket Data Center. Gebruikers van de repository moeten de Git LFS-opdrachtregelclient hebben geïnstalleerd of een GUI-client gebruiken die Git LFS ondersteunt, zoals Sourcetree. Leuk weetje: Steve Streeting, de ontwikkelaar van Atlassian die Sourcetree heeft uitgevonden, levert ook een belangrijke bijdrage aan het Git LFS-project, dus Sourcetree en Git LFS werken vrij goed samen.

1. Er zijn drie eenvoudige manieren om Git LFS te installeren:

a. Gebruik je favoriete pakketbeheerder. git-lfs-pakketten zijn beschikbaar voor Homebrew, MacPorts, dnf en packagecloud; of

b. Download en installeer Git LFS vanaf de projectwebsite; of

c. Installeer Sourcetree, een gratis Git GUI-client die wordt meegeleverd met Git LFS.

2. Zodra je git-lfs hebt, moet je git lfs install uitvoeren om Git LFS te initialiseren (je kunt deze stap overslaan als je Sourcetree hebt geïnstalleerd):

Je hoeft git lfs install maar één keer uit te voeren. Na de installatie op je systeem start Git LFS zichzelf automatisch op wanneer je een repository kloont die Git LFS-inhoud bevat.

Om een nieuwe Git LFS-aware repository te maken, moet je git lfs install uitvoeren nadat je de repository hebt aangemaakt:

Er wordt dan een speciale pre-push Git-hook in je repository geïnstalleerd die Git LFS-bestanden naar de server overbrengt wanneer je git push uitvoert.

Git LFS wordt automatisch ingeschakeld voor alle Bitbucket Cloud-repository's. Voor Bitbucket Data Center moet je Git LFS inschakelen in de instellingen van je repository:

Zodra Git LFS voor je repository is geïnitialiseerd, kun je met git lfs track aangeven welke bestanden je wilt traceren.

Zodra Git LFS is geïnstalleerd, kun je een Git LFS-repository op de gebruikelijke manier klonen met git clone. Aan het einde van het kloonproces checkt Git de standaardbranch uit (meestal de main-versie). Alle Git LFS-bestanden die nodig zijn om het uitcheckproces te voltooien, worden automatisch voor je gedownload. Bijvoorbeeld:

Er zijn vier PNGs in deze repository die worden bijgehouden door Git LFS. Wanneer git clone wordt uitgevoerd, worden Git LFS-bestanden een voor een gedownload terwijl de pointer-bestanden uit je repository worden uitgecheckt.

Als je een repository met een groot aantal LFS-bestanden kloont, biedt de expliciete opdracht git lfs clone veel betere prestaties:

In plaats van de Git LFS-bestanden een voor een te downloaden, wacht de opdracht git lfs clone tot het uitchecken is voltooid. Vervolgens worden alle vereiste Git LFS-bestanden als batch gedownload. Dit maakt gebruik van parallelle downloads en vermindert het aantal HTTP-verzoeken en -processen aanzienlijk (wat vooral belangrijk is om de prestaties op Windows te verbeteren).

Net als bij klonen kun je met een normale git pull zaken ophalen uit een Git LFS-repository. Alle benodigde Git LFS-bestanden worden als onderdeel van het automatische uitcheckproces gedownload zodra de pull is voltooid:

Er zijn geen expliciete opdrachten nodig om Git LFS-inhoud op te halen. Als het uitchecken echter om een onverwachte reden mislukt, kun je alle ontbrekende Git LFS-inhoud voor de huidige commit downloaden met git lfs pull:

Net zoals git lfs clone downloadt git lfs pull je Git LFS-bestanden batchgewijs. Als je weet dat er een groot aantal bestanden is gewijzigd sinds de laatste keer dat je ze hebt opgehaald, kun je het automatisch downloaden via Git LFS uitschakelen tijdens het uitchecken. Vervolgens kun je je Git LFS-inhoud batchgewijs downloaden met een expliciete git lfs pull. Dit kun je doen door je Git-configuratie te negeren met de optie -c wanneer je git pull aanroept:

Aangezien dat nogal veel typewerk is, wil je misschien een eenvoudige Git-alias aanmaken om een Git- en Git LFS-pull in batches voor je uit te voeren:

Dit zal de prestaties aanzienlijk verbeteren als er een groot aantal Git LFS-bestanden moet worden gedownload (nogmaals, vooral in Windows).

Als je een nieuw type groot bestand aan je repository toevoegt, moet je Git LFS vragen dat te traceren door een patroon op te geven met de opdracht git lfs track:

Let op: de aanhalingstekens rondom "*.ogg" zijn belangrijk. Als je ze weglaat, wordt de wildcard uitgebreid met je shell en worden er individuele items aangemaakt voor elk .ogg-bestand in je huidige map:

Git LFS ondersteunt dezelfde patronen die worden ondersteund door .gitignore, bijvoorbeeld:

Deze patronen hebben betrekking op de map waarin je de opdracht git lfs track hebt uitgevoerd. Om het simpel te houden, kun je het beste git lfs track uitvoeren vanuit de root van je repository. Let op: Git LFS ondersteunt geen negatieve patronen zoals .gitignore doet.

Nadat je git lfs track hebt uitgevoerd, zul je een nieuw bestand zien met de naam .gitattributes in de map waaruit je de opdracht hebt uitgevoerd. .gitattributes is een Git-mechanisme om speciaal gedrag te koppelen aan bepaalde bestandspatronen. Git LFS maakt of actualiseert automatisch .gitattributes-bestanden om patronen voor bijgehouden bestanden te koppelen aan de Git LFS-filter. Wijzigingen in het .gitattributes-bestand moet je echter wel zelf doorvoeren naar je repository:

Om het onderhoud te vereenvoudigen kun je het gemakkelijkst alle Git LFS-patronen in één .gitattributes-bestand bewaren door altijd git lfs track uit te voeren vanuit de hoofdmap van je repository. Je kunt echter een lijst weergeven van alle patronen die momenteel door Git LFS worden bijgehouden (en de .gitattributes-bestanden waarin ze zijn gedefinieerd) door git lfs track aan te roepen zonder argumenten:

Met Git LFS kun je het volgen van een bepaald patroon stoppen door simpelweg de juiste regel te verwijderen uit je .gitattributes-bestand of door de opdracht git lfs untrack uit te voeren:

Nadat je git lfs untrack hebt uitgevoerd, moet je zelf de wijzigingen opnieuw doorvoeren in .gitattributes.

Je kunt zoals gewoonlijk committen en pushen naar een repository die Git LFS-inhoud bevat. Als je wijzigingen hebt doorgevoerd in bestanden die door Git LFS worden bijgehouden, zie je wat extra output van git push als de Git LFS-inhoud naar de server wordt overgebracht:

Als het overzetten van de LFS-bestanden om een of andere reden mislukt, wordt de push afgebroken en kun je het veilig opnieuw proberen. Net als Git is Git LFS-opslag adresseerbaar voor inhoud: inhoud wordt opgeslagen onder een sleutel, die een SHA-256-hash is van de inhoud zelf. Dit betekent dat het altijd veilig is om opnieuw te proberen Git LFS-bestanden over te zetten naar de server: je kunt niet per ongeluk de inhoud van een Git LFS-bestand overschrijven met de verkeerde versie.

Om een Git LFS-repository van de ene hostingprovider naar een andere te migreren, kun je een combinatie van git lfs fetch en git lfs push gebruiken, waarbij de optie --all is gespecificeerd.

Ga bijvoorbeeld als volgt te werk om alle Git- en Git LFS-repository's met de naam github naar een remote repo met de naam bitbucket 😉 te verplaatsen:

Git LFS downloadt doorgaans alleen de bestanden die nodig zijn voor commits die je daadwerkelijk lokaal uitcheckt. Je kunt Git LFS echter dwingen om extra content te downloaden voor andere recent aangepaste branches met git lfs fetch --recent:

Dit is handig als je nieuwe Git LFS-content batchgewijs wilt downloaden terwijl je aan het lunchen bent, of als je van plan bent om werk van je teamgenoten te bekijken en later geen content kunt downloaden vanwege de beperkte internetverbinding. Misschien wil je bijvoorbeeld git lfs fetch --recent uitvoeren voordat je in het vliegtuig springt!

Git LFS beschouwt elke branch of tag met een commit die nieuwer dan zeven dagen is als recent. Je kunt het aantal dagen dat als recent wordt beschouwd instellen door de eigenschap lfs.fetchrecentrefsdays in te stellen:

git lfs fetch --recent downloadt standaard alleen Git LFS-inhoud voor de commit via het uiterste van een recente branch of tag.

Je kunt Git LFS echter configureren om content te downloaden voor eerdere commits voor recente branches en tags door de eigenschap lfs.fetchrecentcommitsdays te configureren:

Wees voorzichtig met deze instelling: als je snel veranderende branches hebt, kan dit ertoe leiden dat er een enorme hoeveelheid gegevens wordt gedownload. Het kan echter nuttig zijn als je tussenliggende wijzigingen in een branch wilt bekijken, commits tussen branches eruit wilt pikken of de geschiedenis wilt herschrijven.

Zoals besproken in Een Git LFS-repository verplaatsen tussen hosts, kun je er ook voor kiezen om alle Git LFS-inhoud voor je repository op te halen met git lfs fetch --all:

Je kunt bestanden uit je lokale Git LFS-cache verwijderen met de opdracht git lfs prune:

Hiermee worden alle lokale Git LFS-bestanden verwijderd die als oud worden beschouwd. Een oud bestand is elk bestand waar niet naar wordt verwezen door:

• de uitgecheckte commit
• een commit die nog niet is gepusht (naar origin, of waar lfs.pruneremotetocheck ook op is ingesteld)
• een recente commit

Een recente commit is standaard elke commit die in de afgelopen tien dagen is aangemaakt. Dit wordt berekend door het volgende toe te voegen:

• de waarde van de eigenschap lfs.fetchrecentrefsdays zoals besproken in Extra Git LFS-geschiedenis ophalen (standaard zeven);
• de waarde van de eigenschap lfs.pruneoffsetdays (standaard ingesteld op drie).

Je kunt de prune-offset configureren om Git LFS-inhoud voor een langere periode te behouden:

In tegenstelling tot de ingebouwde 'afvalinzameling' van Git, wordt Git LFS-inhoud niet automatisch opgeschoond. Het is dan ook een goed idee om git lfs prune regelmatig uit te voeren om de grootte van je lokale repository beperkt te houden.

Je kunt testen welk effect een opschoningsbewerking zal hebben met git lfs prune --dry-run:

Test welke Git LFS-objecten precies worden opgeschoond met git lfs prune --verbose --dry-run:

De lange hexadecimale tekenreeksen die in de modus --verbose worden uitgevoerd, zijn SHA-256-hashes (ook bekend als object-ID's of OID's) van de Git LFS-objecten die moeten worden opgeschoond. Je kunt de technieken gebruiken die in Paden of commits vinden die naar een Git LFS-object verwijzen worden beschreven om meer te weten te komen over de objecten die zullen worden opgeschoond.

Als extra veiligheidscontrole kun je de optie --verify-remote gebruiken om te controleren of de externe Git LFS-store een kopie van je Git LFS-objecten bevat voordat ze worden opgeschoond:

Dit maakt het opschoningsproces aanzienlijk langzamer, maar het geeft je gemoedsrust omdat je weet dat opgeschoonde voorwerpen op de server kunnen worden teruggehaald. Je kunt de optie --verify-remote permanent inschakelen voor je systeem door de eigenschap lfs.pruneverifyremotealways globaal te configureren:

Of je kunt verificatie op afstand inschakelen voor alleen de context-repository door de optie --global uit het bovenstaande commando weg te laten.

De Git LFS-opdrachtregelclient ondersteunt het verwijderen van bestanden van de server niet. Hoe je ze verwijdert, hangt dus af van je hostingprovider.

In Bitbucket Cloud kun je Git LFS-bestanden bekijken en verwijderen via Repository-instellingen > Git LFS):

Merk op dat elk Git LFS-bestand wordt geïndexeerd met zijn SHA-256-OID. De paden die naar elk bestand verwijzen, zijn niet zichtbaar via de gebruikersinterface. Dit komt omdat er bij veel verschillende commits tal van paden kunnen zijn die naar een bepaald object kunnen verwijzen. Het opzoeken zou dus een heel langzaam proces zijn.

Om te bepalen wat een bepaald Git LFS-bestand eigenlijk bevat, heb je drie opties:

• Bekijk de voorbeeldweergave van het bestand en het bestandstype in de linkerkolom van de Bitbucket Git LFS-gebruikersinterface;
• Download het bestand via de link in de rechterkolom van de Bitbucket Git LFS-gebruikersinterface. Zoek naar commits die verwijzen naar de SHA-256-OID van het Git LFS-object, zoals besproken in de volgende sectie.

Als je een Git LFS SHA-256 OID hebt, kun je bepalen naar welke commits wordt verwezen met git log --all -p -S :

Deze git log-incantatie genereert een patch (-p) op basis van commits op elke branch (--all) die een regel (-S) toevoegt of verwijdert die de opgegeven tekenreeks bevat (een Git LFS SHA-256-OID).

De patch toont je de commit en het pad naar het LFS-object, en ook wie het heeft toegevoegd en wanneer het werd vastgelegd. Je kunt de commit gewoon uitchecken. Git LFS zal het bestand zo nodig downloaden en in je werkkopie plaatsen.

Als je vermoedt dat een bepaald Git LFS-object zich in je huidige HEAD of in een bepaalde branch bevindt, kun je git grep gebruiken om het bestandspad te vinden dat ernaar verwijst:

Je kunt HEAD of power-ups vervangen door elke ref-, commit- of boomstructuur die het Git LFS-object bevat.

In sommige situaties wil je misschien slechts een subset van de beschikbare Git LFS-inhoud downloaden voor een bepaalde commit. Als je bijvoorbeeld een CI-build configureert om eenheidstests uit te voeren, heb je mogelijk alleen je broncode nodig. Misschien wil je dus zware bestanden uitsluiten die niet nodig zijn om je code samen te stellen.

Je kunt een patroon of submap uitsluiten met git lfs fetch -X (of --exclude):

Als alternatief kun je misschien alleen een bepaald patroon of een bepaalde submap toevoegen. Een geluidstechnicus kan bijvoorbeeld enkel ogg- en wav-bestanden ophalen met git lfs fetch -I (of --include):

Als je insluiten en uitsluiten combineert, worden alleen bestanden opgehaald die overeenkomen met een 'include'-patroon en die niet overeenkomen met een 'exclude'-patroon. Je kunt bijvoorbeeld alles uit je Assets-map, behalve gifs ophalen met:

In- en uitsluitingen ondersteunen dezelfde patronen als git lfs track en .gitignore. Je kunt deze patronen permanent maken voor een bepaalde repository door de configuratie-eigenschappen lfs.fetchinclude en lfs.fetchexclude in te stellen:

Deze instellingen kunnen ook worden toegepast op elke repository in je systeem door de optie --global toe te voegen.

Helaas is er geen eenvoudige manier om conflicten met binaire samenvoegingen op te lossen. Met Git LFS-bestandsvergrendeling kun je bestanden vergrendelen op basis van extensie of bestandsnaam en voorkomen dat binaire bestanden worden overschreven tijdens een samenvoeging.

Om van de functie voor bestandsvergrendeling in LFS te kunnen profiteren, moet je Git eerst vertellen welk type bestanden vergrendelbaar zijn. In het onderstaande voorbeeld wordt de markering '--lockable' aan de opdracht 'git lfs track' toegevoegd, waarbij PSD-bestanden zowel in LFS worden opgeslagen als als vergrendelbaar worden gemarkeerd.

Voeg daarna het volgende toe aan je .gitattributes-bestand:

Gebruik tijdens je voorbereidingen om wijzigingen in een LFS-bestand aan te brengen het vergrendelingscommando om het bestand als vergrendeld te registreren op je Git-server.

Als je het bestand niet meer hoeft te vergrendelen, kun je het verwijderen met de ontgrendelingsopdracht van Git LFS.

Git LFS-bestandsvergrendeling kan worden opgeheven, vergelijkbaar met git push, met behulp van een --force-markering. Gebruik de markering --force niet tenzij je er absoluut zeker van bent dat je weet wat je doet.