Git LFS (Large File Storage)

Qu'est-ce que Git LFS

Git LFS (Large File Storage) est une extension Git open source qui maintient les gros fichiers binaires — vidéos, jeux de données, ressources graphiques, art de jeux vidéo — en dehors de l'historique Git. Au lieu de stocker un fichier de 500 Mo dans le dépôt, Git LFS enregistre un petit pointeur textuel et conserve le contenu réel dans un stockage LFS séparé. Résultat : les clones restent rapides et le dépôt reste léger, même lorsque le projet contient des gigaoctets de ressources.

Ce chapitre explique quand utiliser LFS, comment installer et suivre des fichiers, ce que contient réellement un pointeur, les commandes courantes, le verrouillage de fichiers pour les binaires non fusionnables, ainsi que les pièges fréquents.

Pourquoi les gros fichiers nuisent à Git

Git est conçu pour le texte et stocke l'historique complet de chaque fichier. Il stocke également les fichiers par contenu : lorsqu'un binaire change, Git conserve généralement une copie entière de la nouvelle version plutôt qu'un diff réduit, car les binaires ne se comparent pas proprement. Valider un gros binaire plusieurs fois oblige chaque clone à télécharger toutes les versions pour toujours — même celles dont personne n'a besoin. L'historique gonfle, les clones ralentissent et les push expirent. Git LFS contourne ce problème en versionnant un petit pointeur plutôt que le contenu lourd.

Optez pour LFS lorsque les fichiers sont volumineux et évoluent dans le temps — sources de design, ressources compilées, jeux de données, audio et vidéo. Pour les fichiers qui n'ont jamais besoin d'être versionnés, excluez-les complètement du dépôt avec .gitignore.

Configuration

Commencez par installer Git, puis installez l'extension LFS. Sur la plupart des systèmes, Git LFS est distribué séparément (brew install git-lfs, apt install git-lfs, ou le programme d'installation depuis git-lfs.com). Activez-le une fois par machine :

git lfs install

Updated Git hooks.
Git LFS initialized.

Indiquez à LFS quels fichiers gérer en définissant des motifs à suivre. Cela écrit des règles dans .gitattributes :

git lfs track "*.psd"
git lfs track "*.mp4"
git add .gitattributes

.gitattributes doit être validé afin que chaque collaborateur bénéficie des mêmes règles. À partir de maintenant, les fichiers correspondants sont stockés via LFS automatiquement. Validez et poussez comme d'habitude :

git add design.psd
git commit -m "Add hero design source"
git push

Git envoie le pointeur vers le dépôt et le contenu binaire vers le stockage LFS. Lors d'un nouveau clone, les hooks Git LFS s'activent automatiquement et téléchargent le contenu réel pour le commit extrait.

À quoi ressemble un pointeur

Dans le dépôt, le fichier suivi est remplacé par un petit pointeur textuel qui enregistre le hachage et la taille du contenu :

version https://git-lfs.github.com/spec/v1
oid sha256:9af1c2a3b4d5e6f70819a2b3c4d5e6f70819a2b3c4d5e6f70819a2b3c4d5e6f7
size 471859200

Les trois lignes représentent la version de la spécification, l'identifiant d'objet SHA-256 du contenu (oid), et la taille en octets. C'est la seule empreinte dans l'historique Git — quelques centaines d'octets, quelle que soit la taille de la ressource. Lorsqu'une personne extrait le fichier, Git LFS utilise ce pointeur pour récupérer le contenu réel à la demande.

Commandes courantes

Pour confirmer ce que LFS gère réellement, listez les fichiers suivis :

git lfs ls-files

9af1c2a3b4 * design.psd
1c0ffee5d6 * intro.mp4

Chaque ligne affiche l'identifiant d'objet court, un * lorsque le contenu réel est présent localement (- si seul le pointeur est extrait), et le chemin.

Verrouillage de fichiers

Les binaires comme .psd ou .fbx ne peuvent pas être fusionnés — si deux personnes modifient le même fichier, l'un des ensembles de modifications est perdu. Git LFS ajoute le verrouillage de fichiers afin qu'un coéquipier puisse revendiquer un fichier avant de le modifier :

git lfs lock images/banner.psd
git lfs locks
git lfs unlock images/banner.psd

Marquez un motif comme verrouillable dans .gitattributes pour le rendre en lecture seule jusqu'au verrouillage, ce qui empêche les modifications accidentelles :

git lfs track "*.psd" --lockable

Le verrouillage nécessite le support du serveur (GitHub et GitLab le fournissent).

Déplacer des fichiers existants vers LFS

Le suivi n'affecte que les fichiers validés après l'ajout de la règle. Les fichiers déjà dans l'historique restent dans Git en tant que binaires complets. Pour les déplacer, réécrivez l'historique avec git lfs migrate :

git lfs migrate import --include="*.mp4"

Cela réécrit les commits et modifie donc leurs hachages — coordonnez-vous avec votre équipe et effectuez un push forcé ensuite, comme pour toute réécriture d'historique.

Points à connaître

• Le support serveur est requis. GitHub, GitLab et Bitbucket fournissent tous LFS, souvent avec des quotas de stockage et de bande passante pouvant entraîner des coûts. Un dépôt peut dépasser son quota LFS même si la taille Git reste petite.
• Tout le monde a besoin de l'extension. Toute personne clonant le dépôt doit avoir Git LFS installé, sinon elle verra le texte du pointeur au lieu du fichier réel. Si cela se produit, installer LFS et exécuter git lfs pull résout le problème.
• Les pointeurs sont des objets Git normaux. Les branches, fusions et comparaisons du pointeur fonctionnent normalement ; LFS ne substitue le contenu réel qu'au moment de l'extraction.

Pratique