Stockage de fichiers volumineux Git (LFS)

Lorsque vous extrayez un commit contenant des pointeurs Git LFS, ces pointeurs sont remplacés par des fichiers de votre cache Git LFS local, ou téléchargés depuis le magasin Git LFS distant.

Git LFS est transparent : dans votre copie de travail, vous verrez uniquement le contenu de votre fichier actuel. Autrement dit, vous pouvez utiliser Git LFS sans changer votre workflow Git existant ; exécutez simplement les opérations git checkout, edit, git add et git commit comme d'habitude. Les opérations git clone et git pull seront significativement plus rapides, car vous ne téléchargez que les versions des fichiers volumineux référencés par des commits que vous avez véritablement extraits, et non toutes les versions passées du fichier.

Pour utiliser Git LFS, vous aurez besoin d'un hôte compatible Git LFS, comme Bitbucket Cloud ou Bitbucket Data Center. Les utilisateurs de dépôt auront besoin du client de ligne de commande Git LFS ou d'un client d'interface graphique compatible Git LFS, comme Sourcetree. Anecdote : Steve Streeting, le développeur Atlassian qui a inventé Sourcetree, contribue également activement au projet Git LFS. C'est pourquoi Sourcetree et Git LFS fonctionnent plutôt bien ensemble.

1. Il existe trois façons d'installer facilement Git LFS :

a. Installez-le avec votre gestionnaire de package favori. Les packages git-lfs sont disponibles pour Homebrew, MacPorts, dnf et packagecloud ; ou

b. Télécharger et installer Git LFS à partir du site web du projet ; ou

c. Installez Sourcetree, un client d'interface graphique gratuit livré avec Git LFS.

2. Une fois que git-lfs est sur installé, exécutez git lfs install pour initialiser Git LFS (vous pouvez passer cette étape si vous avez installé Sourcetree) :

Vous ne devez exécuter git lfs install qu'une fois. Une fois initialisé pour votre système, Git LFS effectue automatiquement un bootstrap lorsque vous clonez un dépôt avec du contenu Git LFS.

Pour créer un dépôt compatible Git LFS, vous devez exécuter git lfs install après avoir créé le dépôt :

Cela installe un hook Git pre-push dans votre dépôt qui transfère les fichiers Git LFS vers votre serveur lors de l'exécution de git push.

Git LFS est automatiquement activé pour tous les dépôts Bitbucket Cloud. Pour Bitbucket Data Center, vous devrez activer Git LFS dans les paramètres de votre dépôt :

Une fois Git LFS initialisé pour votre dépôt, vous pouvez spécifier les fichiers à suivre avec git lfs track.

Une fois Git LFS installé, vous pouvez cloner un dépôt Git LFS normalement avec git clone. Au terme du processus de clonage, Git extrait la branche par défaut (généralement, la branche main), et tous les fichiers Git LFS requis pour le processus d'extraction sont automatiquement téléchargés pour vous. Par exemple :

Ce dépôt contient quatre PNG suivis par Git LFS. Lors de l'exécution de git clone, les fichiers Git LFS sont téléchargés individuellement lorsque les fichiers de pointeur sont extraits de votre dépôt.

Si vous clonez un dépôt contenant de nombreux fichiers LFS, la commande explicite git lfs clone assure de bien meilleures performances :

Au lieu de télécharger les fichiers Git LFS en une fois, la commande git lfs clone attend la fin de l'extraction, puis télécharge tous les fichiers Git LFS requis en lot. Cela tire parti des téléchargements parallélisés et réduit considérablement le nombre de requêtes HTTP et de processus engendrés (ce qui est particulièrement important pour améliorer les performances sous Windows).

À l'instar du clonage, vous pouvez faire un pull à partir d'un dépôt Git LFS avec une commande git pull. Tous les fichiers Git LFS nécessaires seront téléchargés dans le cadre du processus de check-out automatique une fois le pull effectué :

Aucune commande explicite n'est requise pour récupérer le contenu Git LFS. Cependant, si la commande échoue pour une raison inattendue, vous pouvez télécharger tout le contenu Git LFS manquant pour le commit actuel avec git lfs pull :

À l'instar de git lfs clone, git lfs pull télécharge vos fichiers Git LFS en lot. Si vous savez qu'un grand nombre de fichiers ont été modifiés depuis votre dernier pull, vous souhaitez peut-être désactiver le téléchargement automatique Git LFS pendant l'extraction, puis télécharger en lot votre contenu Git LFS avec une commande git lfs pull explicite. Pour cela, remplacez votre configuration Git par l'option -c lorsque vous appelez git pull :

Puisqu'il y a beaucoup à saisir, vous souhaitez peut-être créer un simple alias Git pour réaliser un pull Git et Git LFS en lot pour vous :

Cela améliorera grandement les performances lorsqu'un grand nombre de fichiers Git LFS doivent être téléchargés (à nouveau, surtout sous Windows).

Lorsque vous ajoutez un nouveau type de fichier volumineux à votre dépôt, vous devez indiquer à Git LFS de le suivre en spécifiant un modèle à l'aide de la commande git lfs track :

Notez que les guillemets autour de "*.ogg" sont importants. Les omettre étendra le caractère générique à votre invite shell, et des entrées individuelles seront créées pour chaque fichier .ogg dans votre répertoire actuel :

Les modèles pris en charge par Git LFS sont les mêmes que ceux pris en charge par .gitignore, par exemple :

Ces modèles dépendent du répertoire dans lequel vous exécutez la commande git lfs track. Pour faire simple, il vaut mieux exécuter git lfs track à la source de votre dépôt. Notez que Git LFS ne prend pas en charge les modèles négatifs comme .gitignore.

Après avoir exécuté git lfs track, vous remarquerez un nouveau fichier appelé .gitattributes dans le répertoire à partir duquel vous avez exécuté la commande. .gitattributes est un mécanisme Git qui permet de lier des comportements spéciaux à certains modèles de fichiers. Git LFS crée ou met à jour automatiquement les fichiers .gitattributes pour lier les modèles de fichiers trackés au filtre Git LFS. Toutefois, vous devrez commiter vous-même tous les changements apportés au fichier .gitattributes vers votre dépôt :

Pour faciliter la maintenance, il est plus simple de conserver tous les modèles Git LFS dans un fichier .gitattributes unique en exécutant toujours git lfs track depuis la racine de votre dépôt. Toutefois, vous pouvez afficher une liste de tous les modèles actuellement suivis par Git LFS (et des fichiers .gitattributes dans lesquels ils sont définis) en appelant git lfs track sans argument :

Vous pouvez arrêter de suivre un modèle particulier avec Git LFS en retirant simplement la ligne appropriée de votre fichier .gitattributes, ou en exécutant la commande git lfs untrack :

Après avoir exécuté git lfs untrack, vous devrez à nouveau commiter vous-mêmes les changements vers .gitattributes.

Vous pouvez faire un commit et un push normalement vers un dépôt avec du contenu Git LFS. Si vous avez commité des changements vers des fichiers suivis par Git LFS, vous verrez des sorties supplémentaires depuis git push à mesure que le contenu Git LFS est transféré vers le serveur.

Si le transfert des fichiers LFS échoue pour une quelconque raison, le push est annulé, et vous pouvez réessayer en toute sécurité. À l'instar de Git, le stockage Git LFS est adressable en contenu : le contenu est stocké avec une clé correspondant à une empreinte SHA-256 du contenu lui-même. Autrement dit, vous pouvez toujours réessayer sans risque de transférer des fichiers Git LFS vers le serveur ; vous ne pouvez pas remplacer accidentellement le contenu d'un fichier Git LFS par une mauvaise version.

Pour migrer un dépôt Git LFS d'un fournisseur d'hébergement vers un autre, vous pouvez utiliser une combinaison de git lfs fetch et git lfs push, en spécifiant l'option --all.

Par exemple, pour migrer tous les dépôts Git et Git LFS depuis un dépôt distant nommé github vers un dépôt distant nommé bitbucket 😉 :

Git LFS ne télécharge normalement que les fichiers requis pour les commits que vous extrayez localement. Toutefois, vous pouvez forcer Git LFS à télécharger du contenu supplémentaire pour d'autres branches récemment modifiées avec git lfs fetch --recent :

Ceci est utile pour télécharger en lots du nouveau contenu Git LFS pendant votre pause déjeuner, ou si vous envisagez d'examiner le travail de vos coéquipiers et que vous ne pourrez pas télécharger du contenu plus tard en raison d'une connexion Internet limitée. Par exemple, vous souhaitez peut-être exécuter git lfs fetch --recent avant de prendre l'avion !

Git LFS considère les branches ou les tags contenant un commit antérieur à sept jours comme récents. Vous pouvez configurer le nombre de jours considérés comme récents en définissant la propriété lfs.fetchrecentrefsdays :

Par défaut, git lfs fetch --recent téléchargera uniquement le contenu Git LFS pour le commit à la pointe d'une branche ou d'un tag récent.

Toutefois, vous pouvez configurer Git LFS pour qu'il télécharge le contenu de commits antérieurs sur des branches et des tags récents en configurant la propriété lfs.fetchrecentcommitsdays :

Utilisez ce paramètre avec précaution : si vous disposez de branches évoluant rapidement, cela peut provoquer le téléchargement d'une immense quantité de données. Toutefois, cela peut être utile si vous devez passer en revue des changements interstitiels sur une branche, sélectionner des commits dans plusieurs branches ou réécrire l'historique.

Comme nous l'avons vu dans Migration d'un dépôt Git LFS entre des hôtes, vous pouvez également choisir d'extraire tout le contenu Git LFS de votre dépôt avec git lfs fetch --all:

Vous pouvez supprimer des fichiers de votre cache Git LFS local avec la commande git lfs prune :

Cela supprimera tous les fichiers Git LFS locaux considérés comme anciens. Un fichier ancien est un fichier qui n'est pas référencé par :

• le commit en cours d'extraction ;
• un commit qui n'a pas encore été pushé (vers l'origine ou vers la valeur définie pour lfs.pruneremotetocheck)
• un commit récent.

Par défaut, un commit récent est un commit créé au cours des dix derniers jours. Cela est calculé en ajoutant :

• la valeur de la propriété lfs.fetchrecentrefsdays discutée dans Fetcher l'historique Git LFS supplémentaire (définie par défaut sur sept) ; et
• la valeur de la propriété lfs.pruneoffsetdays (qui, par défaut est trois).

Vous pouvez configurer la sortie de suppression pour conserver plus longtemps le contenu Git LFS :

Contrairement au nettoyage de type garbage collection intégré à Git, le contenu Git LFS n'est pas supprimé automatiquement. Exécuter régulièrement git lfs prune est une bonne idée pour limiter la taille de votre dépôt local.

Vous pouvez tester l'effet d'une opération de suppression avec git lfs prune --dry-run :

Et vous pouvez connaître exactement les objets Git LFS qui seront supprimés avec git lfs prune --verbose --dry-run :

Les longues chaînes hexadécimales générées par le mode --verbose sont des empreintes SHA-256 (également connues comme ID d'objet ou OID) des objets Git LFS à supprimer. Vous pouvez utiliser les techniques décrites dans Recherche de chemins ou de commits faisant référence à un objet Git LFS pour en savoir plus sur les objets qui seront supprimés.

À titre de contrôle de sécurité supplémentaire, vous pouvez utiliser l'option --verify-remote pour déterminer si le magasin Git LFS distant dispose d'une copie de vos objets Git LFS avant qu'ils ne soient supprimés :

Le processus de suppression est considérablement ralenti, mais soyez tranquille, tous les objets supprimés sont récupérables depuis le serveur. Vous pouvez en permanence activer l'option --verify-remote pour votre système en configurant la propriété lfs.pruneverifyremotealways à l'échelle globale :

Vous pouvez également activer la vérification à distance uniquement pour le dépôt de contexte en omettant l'option --global de la commande ci-dessus.

Le client de ligne de commande Git LFS ne prend pas en charge la suppression de fichiers depuis le serveur, donc la façon de les effacer dépend de votre fournisseur d'hébergement.

Dans Bitbucket Cloud, vous pouvez afficher et supprimer les fichiers Git LFS via Paramètres de dépôt > Git LFS :

Notez que chaque fichier Git LFS est indexé par son OID SHA-256. Les chemins qui référencent chaque fichier ne sont pas visibles via l'interface utilisateur. C'est parce qu'il peut exister de nombreux chemins différents pour de nombreux commits différents qui peuvent faire référence à un objet donné. Les rechercher serait donc un processus lent.

Pour déterminer ce qu'un fichier Git LFS contient réellement, vous avez trois possibilités :

• Consulter l'image d'aperçu et le type du fichier dans la colonne de gauche de l'interface utilisateur Bitbucket Git LFS.
• Téléchargez le fichier à l'aide du lien dans la colonne de droite de l'interface utilisateur Bitbucket Git LFS. Recherchez les commits qui référencent l'OID SHA-256 de l'objet, comme expliqué à la section suivante.

Si vous disposez d'un OID Git LFS SHA-256, vous pouvez déterminer les commits qui y font référence avec git log --all -p -S :

Cet appel git log génère un patch (-p) à partir des commits sur chaque branche (--all) qui ajoutent ou retirent une ligne (-S) contenant la chaîne spécifiée (OID Git LFS SHA-256).

Le patch vous montre le commit et le chemin vers l'objet LFS, et vous indique qui l'a ajouté et la date du commit. Vous pouvez simplement faire un checkout du commit : si nécessaire, Git LFS téléchargera le fichier et le placera dans votre copie de travail.

Si vous suspectez qu'un objet Git LFS spécifique se trouve dans votre HEAD actuel ou sur une branche spécifique, vous pouvez utiliser git grep pour rechercher le chemin d'accès au fichier qui le référence :

Vous pouvez remplacer HEAD ou power-ups par toute réf, tout commit ou toute arborescence contenant l'objet Git LFS.

Dans certains cas, vous souhaiterez peut-être télécharger uniquement un sous-ensemble du contenu Git LFS disponible pour un commit spécifique. Par exemple, lorsque vous configurez un build de CI pour exécuter des tests unitaires, vous avez peut-être uniquement besoin de votre code source et souhaitez exclure les fichiers lourds qui ne sont pas nécessaires pour faire un build de votre code.

Vous pouvez exclure un modèle ou un sous-répertoire avec git lfs fetch -X (ou --exclude) :

Vous souhaitez peut-être également inclure un modèle ou un sous-répertoire spécifique. Par exemple, un ingénieur du son récupère juste les fichiers ogg et wav avec git lfs fetch -I (ou --include) :

Si vous combinez « includes » et « excludes », seuls les fichiers qui correspondent à un modèle « include » et qui ne correspondent pas à un modèle « exclude » seront fetchés. Par exemple, vous pouvez tout fetcher dans votre répertoire Assets, à l'exception des gifs avec :

Les modèles « excludes » et « includes » prennent en charge les mêmes modèles que git lfs track et .gitignore. Vous pouvez rendre ces modèles permanents pour un dépôt spécifique en définissant les propriétés de configuration lfs.fetchinclude et lfs.fetchexclude :

Ces paramètres peuvent également s'appliquer à chaque dépôt sur votre système en ajoutant l'option --global.

Malheureusement, il n'existe pas de moyen simple de résoudre les conflits de merge binaire. Avec le verrouillage des fichiers de Git LFS, vous pouvez verrouiller les fichiers par extension ou par nom de fichier, et empêcher les fichiers binaires d'être écrasés lors d'un merge.

Afin de profiter de la fonctionnalité de verrouillage de fichiers de LFS, vous devez d'abord indiquer à Git quel type de fichiers sont verrouillables. Dans l'exemple ci-dessous, le flag « --lockable » est ajouté à la commande « git lfs track » qui stocke les fichiers PSD dans LFS et les marque comme verrouillables.

Ajoutez ensuite la commande suivante à votre fichier .gitattributes :

Lorsque vous vous préparez à apporter des changements à un fichier LFS, vous utiliserez la commande lock afin d'enregistrer le fichier comme verrouillé sur votre serveur Git.

Une fois que vous n'avez plus besoin du verrou de fichier, vous pouvez le supprimer en utilisant la commande unlock de Git LFS.

Les verrous de fichiers Git LFS peuvent être remplacés, comme pour git push, en utilisant un flag --force. N'utilisez pas le flag --force si vous n'êtes pas absolument sûr de ce que vous faites.