Pourquoi et comment utiliser Git LFS ?
Préambule
Git LFS (Large File Storage) est une fonctionnalité de Git initialisée par GitHub en 2015, qui permet de stocker les fichiers “lourds” tels que les vidéos, graphiques, grosses archives, et autres sur des serveurs distants grâce à des pointeurs de texte.
Désormais, Git LFS a été adopté par tous les logiciels de systèmes de gestion de Git, que ce soit GitlLab, Bitbucket, etc…
TL;DR
Vous tombez sur le message d’erreur suivant ? Vous avez (peut-être) besoin de Git LFS. J’explique dans cet article dans quels cas vous en avez besoin, et dans lesquels vous pouvez pallier autrement au problème.
Installation
Pré-requis
Pour utiliser Git LFS, vous devrez l’installer sur votre machine en local. Pour cela, il faut s’assurer d’avoir Git en version 1.8.2 minimum, grâce à la commande suivante :
$ git --versionSi vous avez une version suffisante, vous pouvez passer à l’installation de Git LFS.
Debian et Ubuntu
Depuis Debian 10 et Ubuntu 18.04, les OS proposent un package, et l’installation se fait simplement, en trois lignes de commande :
$ curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash$ sudo apt-get install git-lfs$ git lfs install
Windows
Il suffit de télécharger l’installeur puis de le lancer. Ensuite, il faut exécuter une seule ligne de commande :
$ git lfs installMacOS
Avec HomeBrew, l’installation se fait en trois commandes également :
$ brew update$ brew install git-lfs$ git lfs install
Ces procédures d’installation ont été prise sur la procédure officielle. Vous trouverez dessus les procédures pour d’autres OS, ou via un Docker Recipe.
Utilisation
Nouveau projet
Si vous partez d’un nouveau projet et que vous voulez initialiser un projet utilisant Git LFS pour un ficher en particulier, certains types de fichiers, ou même des dossiers, il vous suffira de l’indiquer à votre Git avant de les pousser sur le dépôt.
# directory by path
$ git lfs track "assets/*"# directory trees
$ git lfs track "assets/**/*"# one file by path
$ git lfs track "path/to/file.example"# multiplie files by file type
$ git lfs track "*.tar.gz"
Ensuite, vous remarquerez qu’un fichier nommé .gitattributes a été généré. Si vous l’ouvrez vous verrez que celui-ci contient des informations sur le Git LFS, notamment quels fichiers doivent être traqués par ce système de Large Files. Il ne faudra pas oublier de l’ajouter avec un git add .gitattributes et le commit/push sur le dépôt.
Une fois que vous aurez fait cela, le logiciel de gestion de versions que vous aurez choisi se chargera du reste. Votre projet est prêt à utiliser le Large File Storage !
Projet existant
Si vous partez d’un projet existant qui n’utilisait pas Git LFS, mais qui doit l’utiliser maintenant, il y aura quelques manipulations supplémentaires.
Le cas ne se présente pas souvent, mais voici un cas où ça peut arriver (c’est exactement ce cas qui m’est arrivé récemment pour un client) :
Un projet a été développé en utilisant une plateforme Git comme par exemple Bitbucket SaaS, et vous devez le migrer pour une raison ou une autre sur une autre plateforme comme GitHub SaaS. De base, toutes les plateformes n’ont pas forcément les mêmes limites de taille maximale pour leurs fichiers avant de devoir passer sur du LFS. Sur des plateformes auto-hébergées, c’est un élément configurable.
Vous saurez très vite s’il doit mettre mis en place, car vous aurez un refus du git push accompagné de ce message d’erreur dans votre console (erreur vue plus haut) :
La procédure que nous avons suivi pour cette migration a été la suivante :
- Changement de l’ancien dépôt de code vers le nouveau :
$ git remote set-url origin ${NEW_REPO}Ceci remplacement l’adresse du dépôt Git de destination. Si vous souhaitez conserver l’ancien repository pour faire une migration “progressive” pour une raison ou une autre, vous pouvez également avoir plusieurs remotes sur le même projet en modifiant origin par le nom de votre choix pour le nouveau remote. Ensuite, il faudra s’assurer de bien garder la cohérence entre les deux dépôts.
- Reprendre la procédure décrite plus haut pour un l’installation dans un nouveau projet
- Ensuite, il va falloir vous assurer que les anciens fichiers répondant aux critères de fichier à ajouter au Git LFS soient bien ajoutés. En effet le “track” n’est pas rétroactif, donc si vous traquez les
tgz, il faut vous assurer que tous lestgzdéjà présents dans l’historique soient bien ajoutés :
Si vous souhaitez vous assurer que vous ne traquerez que les bons fichiers, vous pouvez effectuer un “dry run” de la migration :
$ git lfs migrate info --everything --include="*.tgz"Une fois que cela est fait et si cela vous convient, vous pouvez lancer la migration (le --verbose étant bien sûr optionnel) :
$ git lfs migrate import --everything --include="*.tgz" --verboseCette commande fait un rewrite des anciens commits comportant des fichiers concernés pour que ceux-ci collent avec l’utilisation du Git LFS.
- (Optionnel) Si vous voulez vous assurer que tous les fichiers voulus ont bien été ajoutés, vous pouvez lister les fichiers ajoutés au système LFS grâce à la commande suivante :
$ git lfs ls-files/!\ Attention ! Certains logiciels de dépôt de code ont une limite d’utilisation de Git LFS. Par exemple, GitHub a une limite mensuelle gratuite de 1GB de stockage et autant de bande passante par “organisation” ou compte utilisateur, au-delà il faudra payer. Cette jauge (pour GitHub) est visible à cette adresse ou dans la section “settings > billing” de votre organisation. /!\
Il ne faut pas oublier que chaque personne qui interagira sur le projet devra suivre la procédure d’installation de Git LFS sur son environnement.
Résultat
Comme résultat, vous aurez une petite indication qui sera affichée dans votre logiciel de dépôt de code, en vous rendant sur le fichier concerné.
GitHub
GitLab
À part ce petit point d’information, tout sera totalement transparent pour vous.
Disclaimer
Le système des Large File Storage peut être très pratique dans certains cas, mais avant de l’utiliser, soyez sûr que vous en avez réellement besoin et qu’une autre solution n’est pas meilleure pour le projet.
Voici un cas (qui est également ce qui s’est passé dans le projet dont je fais référence plus haut), dans lequel vous ne devriez pas avoir besoin de Git LFS :
Vous avez un projet JavaScript, avec dedans un module personnalisé développé par vous ou par une société tiers ou partenaire. Ce module est privé, et n’est donc pas publié sur le Hub NPM. Dans le projet tel qu’il était fait avant notre reprise, ce module personnalisé était sous format .tar.gz, et celui-ci était appelé dans les dépendances du fichier package.json de la manière suivante :
“modulename”: “file:path/to/filename-version.tar.gz”
Typiquement dans ce cas, vous devriez trouver une alternative plus propre et pérenne pour votre application. En effet, en faisant cela, à la mise à jour de l’application, vous devrez mettre à jour le .tar.gz, et changer la version au fur et à mesure dans le package.json, le versionning n’est pas des plus simples et rapides.
Soit vous publiez votre package sur NPM en mode privé ou sur un Nexus (ou autre) restreint. Soit vous n’avez pas ce genre d’outil dans votre organisation et le publiez directement dans votre gestionnaire de code : ici pour GitHub, ou encore là pour GitLab par exemple. Ainsi, ce package sera directement lié à votre projet et vous aurez tout au même endroit. Cela fonctionne pour les packages NPM, Composer, NuGet, Maven, et d’autres…
Conclusion
Il est bon et utile de connaître l’existence de Git LFS et comment s’en servir, cela pourra vous sortir de certaines situations délicates, surtout lors de la reprise d’anciens projets ne respectant pas certaines normes ou bonnes pratiques.
En revanche, ce système n’est pas à utiliser à outrance. Avant de l’utiliser, assurez-vous qu’il n’y ait pas de manière plus propre de régler votre problème.
