Пошук уроків, статей та іншого контенту
Зберігаємо бінарні й великі файли через Git LFS та налаштовуємо його для команди й CI.
Git зберігає кожну версію файлу в історії. Для текстових файлів це зазвичай зручно: Git ефективно зберігає відмінності між версіями.
Для великих бінарних файлів підхід менш ефективний:
зображення, відео, аудіо, архіви та моделі не стискаються між версіями так само добре;
кожна нова версія збільшує розмір Git-репозиторію;
клонування та отримання змін стають повільнішими;
видалення файлу з робочої директорії не видаляє його старі версії з історії.
Git LFS (Large File Storage) зберігає великі файли окремо від основних Git-об’єктів.
У Git-репозиторії замість самого великого файлу зберігається невеликий текстовий файл-покажчик:
version https://git-lfs.github.com/spec/v1
oid sha256:...
size 5242880Сам вміст файлу зберігається у LFS-сховищі, яке має підтримувати Git-сервер.
Git LFS потрібно встановити на комп’ютер розробника та в середовищі CI.
Після встановлення активуйте його для поточного користувача:
git lfs installЦю команду зазвичай достатньо виконати один раз. Вона налаштовує Git hooks і необхідні параметри для роботи LFS.
Перевірити встановлення можна так:
git lfs versionЯкщо команда git lfs не знайдена, Git LFS ще не встановлено або його немає в PATH.
Нехай проєкт містить великі файли Photoshop, відео та архіви. Спочатку вкажемо шаблони, які потрібно зберігати через LFS:
git lfs track "*.psd"
git lfs track "*.mp4"
git lfs track "assets/**/*.zip"Після цього Git LFS створить або змінить файл .gitattributes.
Приклад його вмісту:
*.psd filter=lfs diff=lfs merge=lfs -text
*.mp4 filter=lfs diff=lfs merge=lfs -text
assets/**/*.zip filter=lfs diff=lfs merge=lfs -textФайл .gitattributes потрібно додати до репозиторію:
git add .gitattributes
git commit -m "Configure Git LFS for large files"
.gitattributesє частиною конфігурації проєкту, тому його потрібно зберігати в Git і передавати команді разом з іншими файлами.
Тепер можна додати великий файл звичайним способом:
git add assets/design.psd
git commit -m "Add design source file"
git push origin mainGit LFS перехопить операцію додавання за шаблоном і завантажить вміст файлу до LFS-сховища під час push.
Нижче наведено послідовність команд для нового або вже наявного репозиторію:
# Увімкнути Git LFS на локальному комп'ютері
git lfs install
# Налаштувати шаблони великих файлів
git lfs track "*.psd"
git lfs track "*.mp4"
git lfs track "assets/models/**/*.bin"
# Перевірити створений файл правил
cat .gitattributes
# Додати правила та файли до індексу
git add .gitattributes
git add assets/design.psd
git add assets/demo.mp4
git add assets/models/model.bin
# Перевірити, які файли відстежує LFS
git lfs status
# Зафіксувати зміни
git commit -m "Add large assets with Git LFS"
# Передати коміт і LFS-об'єкти на сервер
git push origin main
# Показати файли, які зберігаються через LFS
git lfs ls-filesКоманда git lfs ls-files показує файли, які Git LFS розпізнає в поточному checkout.
Якщо Git LFS встановлено до клонування, стандартний git clone зазвичай завантажує справжній вміст LFS-файлів:
git clone git@example.com:team/project.git
cd project
git lfs ls-filesЯкщо Git LFS не встановлено, замість великих файлів можна побачити текстові покажчики. Це не пошкодження репозиторію: локальний Git просто не зміг виконати LFS-фільтри.
Після встановлення LFS у вже клонованому репозиторії виконайте:
git lfs install
git lfs pullgit lfs pull завантажує потрібні LFS-об’єкти та відновлює файли в робочій директорії.
Git LFS надає окремі команди для отримання та відновлення файлів:
git lfs fetch
git lfs checkoutgit lfs fetch завантажує LFS-об’єкти з сервера;
git lfs checkout відновлює їх у робочій директорії.
У більшості звичайних сценаріїв зручніше використовувати:
git lfs pullЩоб завантажити лише LFS-файли для певної гілки або діапазону комітів, можна обмежити fetch:
git lfs fetch origin mainЯкщо файл ще не був закомічений, достатньо додати правило перед git add:
git lfs track "*.zip"
git add .gitattributes
git add backup.zip
git commit -m "Store archive with Git LFS"Якщо файл уже був доданий у Git без LFS, додавання шаблону не змінить старий коміт автоматично. Потрібно повторно додати файл після налаштування LFS:
git lfs track "*.zip"
git add .gitattributes
git rm --cached backup.zip
git add backup.zip
git commit -m "Move archive to Git LFS"У цьому випадку нова версія файлу зберігатиметься через LFS, але попередня велика версія все ще залишиться в історії Git.
Якщо великий файл уже багато разів комітили без LFS, для зменшення репозиторію потрібно переписати історію.
Наприклад:
git lfs migrate import --include="*.zip,*.psd" --everythingКоманда:
знаходить файли, що відповідають шаблонам;
замінює їх у всій історії на LFS-покажчики;
створює або оновлює потрібні правила .gitattributes.
Переписування історії змінює ідентифікатори комітів. Після цього потрібно передати оновлену історію на сервер:
git push --force-with-lease origin mainТаку операцію потрібно узгодити з усією командою. Після переписування історії інші розробники мають повторно клонувати репозиторій або окремо синхронізувати свої локальні гілки.
Перед міграцією варто створити резервну гілку або тег:
git branch backup-before-lfs-migration
git tag backup-before-lfs-migrationУ командному репозиторії важливо дотримуватися кількох правил:
Git LFS має бути встановлено у всіх розробників.
git lfs installПравила зберігаються в .gitattributes.
Не покладайтеся на локальне налаштування, якого немає в репозиторії.
Шаблони мають бути конкретними.
Наприклад:
assets/**/*.bin filter=lfs diff=lfs merge=lfs -textне змусить LFS обробляти всі файли проєкту, а лише бінарні файли в потрібному каталозі.
Git-сервер має підтримувати Git LFS.
Одного локального встановлення недостатньо: сервер повинен мати налаштоване LFS-сховище й дозволяти користувачам завантажувати та отримувати LFS-об’єкти.
Потрібно враховувати сховище та трафік.
LFS-файли зберігаються окремо, але для них можуть діяти власні обмеження сховища, пропускної здатності або прав доступу.
CI-середовище також повинно вміти завантажувати LFS-файли. Загальна послідовність має такий вигляд:
#!/usr/bin/env bash
set -euo pipefail
# Увімкнути Git LFS у середовищі CI
git lfs install
# Завантажити LFS-файли після checkout
git lfs pull
# Перевірити наявність необхідного бінарного файлу
test -f assets/models/model.bin
# Запустити перевірки або збірку проєкту
npm ci
npm testВажливо, щоб крок checkout у CI не вимикав отримання LFS-файлів. Якщо середовище навмисно використовує режим без автоматичного завантаження, LFS-файли потрібно отримати явно:
git lfs pullДля діагностики в CI корисні такі команди:
git lfs env
git lfs status
git lfs ls-filesЯкщо CI бачить замість файлу текстовий покажчик, перевірте:
чи встановлено Git LFS;
чи виконано git lfs install;
чи виконується git lfs pull;
чи має CI-доступ до LFS-сховища;
чи відповідає checkout потрібному коміту та гілці.
Не кожному розробнику потрібні всі великі файли. Щоб не завантажувати LFS-вміст автоматично, можна клонувати репозиторій із вимкненим автоматичним завантаженням:
GIT_LFS_SKIP_SMUDGE=1 git clone git@example.com:team/project.git
cd projectУ такому режимі робочі файли LFS залишаться покажчиками. Потрібні файли можна завантажити пізніше:
git lfs pull --include="assets/models/**"Або виключити непотрібний каталог:
git lfs pull --exclude="assets/video/**"Це корисно для великих репозиторіїв, де частина ресурсів потрібна лише окремим командам.
git lfs ls-filesПоказує файли поточного checkout, які зберігаються через Git LFS.
git lfs statusДопомагає перевірити, які LFS-файли змінено, додано або очікують обробки.
git lfs envПоказує версію LFS, налаштовані endpoint-и та параметри фільтрів.
git check-attr filter diff merge -- assets/design.psdОчікуваний результат для LFS-файлу міститиме приблизно такі атрибути:
assets/design.psd: filter: lfs
assets/design.psd: diff: lfs
assets/design.psd: merge: lfsЯкщо для файлу не встановлено filter: lfs, перевірте шаблон у .gitattributes і шлях до файлу.
Для нового великого файлу процес виглядає так:
Визначити тип або каталог файлів, які потрібно передавати через LFS.
Виконати git lfs track.
Додати .gitattributes до коміту.
Додати сам файл через git add.
Перевірити результат за допомогою git lfs status або git lfs ls-files.
Створити коміт.
Виконати git push.
Переконатися, що CI та інші розробники можуть отримати LFS-вміст.
.gitattributesЯкщо виконати git lfs track, але не закомітити .gitattributes, інші розробники та CI не отримають правила відстеження.
Правильно:
git add .gitattributes
git commit -m "Configure Git LFS"git addПравило LFS застосовується під час додавання файлу до індексу. Якщо файл уже був проіндексований, повторно додайте його:
git lfs track "*.bin"
git add .gitattributes
git rm --cached assets/model.bin
git add assets/model.binЦе часто означає, що:
Git LFS не встановлено;
не виконано git lfs pull;
немає доступу до LFS-сервера.
Перевірте:
git lfs install
git lfs pullЗвичайне видалення прибирає файл лише з поточного стану. Старі версії залишаються в історії. Для їх перенесення в LFS або видалення потрібне переписування історії.
git lfs migrate import --everything змінює коміти. Не виконуйте міграцію в спільному репозиторії без узгодження та резервної копії.
Переконайтеся, що в CI є Git LFS і явно виконується:
git lfs install
git lfs pullТакож перевірте права доступу CI до LFS-сховища.
Git LFS зберігає великі бінарні файли окремо від основної Git-історії.
Команда git lfs track додає правила для типів файлів або каталогів.
Правила зберігаються у файлі .gitattributes, який потрібно комітити в репозиторій.
Для отримання справжнього вмісту LFS-файлів використовують git lfs pull.
Уже закомічені великі файли можна перенести в LFS через git lfs migrate import.
Міграція історії змінює коміти й потребує узгодження з командою.
У CI потрібно встановити Git LFS, отримати LFS-файли та перевірити доступ до LFS-сховища.
Команди git lfs status, git lfs ls-files і git lfs env допомагають перевіряти налаштування та знаходити проблеми.