Git LFS: хранение больших файлов в Git

Логотип Git

Быстрые ссылки

Как работает Git Large File Storage (LFS)
Где можно использовать Git LFS
Установка и использование Git LFS
Миграция в Git LFS

Как работает Git Large File Storage (LFS)

Коротко: Git хранит снимки файлов в истории, и при изменении большого файла его несколько версий быстро увеличивают объём репозитория. Git LFS решает это, сохраняя в репозитории не сам большой бинарник, а небольшой текстовый указатель на него. Клиент при клоне или checkout загружает содержимое из внешнего хранилища LFS.

Пояснение по механике:

Git использует модель снимков (snapshots) и объектное хранилище; хотя пользователю показываются диффы, внутри Git хранит объекты и собирает из них снимки.
Большие бинарные файлы плохо сочетаются с этой моделью: каждое изменение создаёт новый объект, и даже с packfile’ами репозиторий растёт.
Git LFS внедряет фильтры clean/smudge: при добавлении файла в индекс он заменяется специальным указателем, а при checkout Git LFS «смазывает» указатель в реальный файл.

Пример содержимого указателя (файл в репозитории вместо бинарника):

version https://git-lfs.github.com/spec/v1
oid sha256:
size: 12345

Важно: указатель — понятный текстовый файл небольшого размера. При clone Git получает минимальную историю, а содержимое больших файлов загружает отдельно только по мере необходимости.

Плюсы:

Быстрый клон репозитория (меньше данных в истории).
Менее «тяжёлая» локальная копия для разработчиков.
Удобно для двоичных артефактов (видео, образы, большие датасеты).

Минусы и ограничения:

Хранение файлов вне репозитория требует дополнительного дискового пространства на сервере LFS и пропускной способности при загрузках.
Некоторые операции по истории (pack, dedupe) работают хуже, потому что данные хранятся отдельно.
Требуется поддержка LFS на серверной стороне (GitHub, GitLab, Bitbucket или собственный сервер).

Примечание по терминам: «pointer» — текстовый файл-заместитель; «смазка/очистка» (smudge/clean) — фильтры, которые подставляют реальное содержимое при checkout и восстанавливают указатель при добавлении в индекс.

Где можно использовать Git LFS

Git LFS полезен, когда в репозитории появляются файлы, заметно превышающие размер типичных исходников (десятки МБ и выше). Частые случаи:

мультимедиа (видео, аудио, большие изображения);
модели машинного обучения и датасеты;
двоичные бандлы, сборки, артефакты тестов.

Поставщики и квоты (проверьте актуальность у вашего провайдера):

GitHub поддерживает Git LFS. В некоторых описаниях указывается лимит в 100 МБ на файл для обычного Git (без LFS) и начальный LFS-квот в 10 ГБ для учётной записи; дополнительные пакеты хранилища и трафика предоставляются за плату через Billing. Точные цифры и цены уточняйте в документации провайдера.

/wordpress/wp-content/uploads/csit/2021/08/fd411e22.png

Если вы хотите полностью контролировать хранилище LFS (или у вас требования по хранению данных на собственной инфраструктуре), рекомендуем рассмотреть self-hosted GitLab или специальные LFS-серверы.

Установка и базовое использование Git LFS

Скачайте и установите Git LFS с официального сайта или пакета для вашей ОС.

/wordpress/wp-content/uploads/csit/2021/08/7a829e2b.png

Запустите команду установки/инициализации в репозитории (в macOS/Linux/Windows Git Bash):

git lfs install

Отслеживание типов файлов: Git LFS не включает автотрек по размеру — вы указываете шаблоны файлов, которые нужно перевести в LFS. Это делается командой git lfs track, которая добавляет правила в .gitattributes:

git lfs track "*.dat"

После этого добавьте и зафиксируйте файл .gitattributes в репозитории:

git add .gitattributes
git commit -m "Track .dat files with Git LFS"

Просмотр состояния LFS-подсистемы:

git lfs ls-files

git lfs status

Ключевые примечания при повседневной работе:

Всегда коммитьте .gitattributes — он управляет, какие файлы должны быть LFS-помечены для всех участников.
При clone Git загрузит указатели; чтобы получить реальные данные, Git LFS скачает содержимое (можно включать/выключать через параметры).
Учитывайте трафик и хранение: загрузка больших файлов потребляет bandwidth и место.

Миграция существующего репозитория в Git LFS

Если вы уже закоммитили большие файлы в историю, просто начать track не переместит старые версии в LFS. Для этого используется инструмент миграции:

Примеры команд:

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

или для перевода всех подходящих объектов в LFS:

git lfs migrate import --everything

После переписывания истории часто требуется форс-пуш:

git push --force


Важные эффекты миграции:

- История веток переписывается — у всех участников изменятся идентификаторы коммитов. Согласуйте миграцию с командой.
- Внешние зеркала и CI могут потребовать обновления настроек или повторной настройки.
- Backup: перед миграцией сделайте резервную копию существующего репозитория.

### Пошаговый план миграции (Playbook)

1. Оцените текущую историю: найдите файлы по расширениям и по размеру (скрипты find/du или git-sizer).
2. Определите шаблоны для git lfs track и добавьте их в .gitattributes.
3. Выполните локальную миграцию на отдельной ветке:
   - git checkout -b lfs-migration
   - git lfs migrate import --include="<шаблоны>" --include-ref=refs/heads/lfs-migration
4. Проверить локально: git clone --local, git lfs ls-files, открыть несколько коммитов и убедиться, что большие файлы стали указателями.
5. Забэкапьте серверную копию (git bundle или зеркалирование).
6. Согласуйте с командой дату форс-пуша и инструкции по синхронизации.
7. Форс-пуш в центральный репозиторий и рассылка инструкций для разработчиков (как перезаписать локальные ветки и синхронизироваться).
8. Мониторинг: проверить CI, интеграции и размер репозитория после миграции.

### Откат и план действий при ошибке

- До форс-пуша достаточно удалить локальную ветку миграции и восстановить из резервной копии.
- После форс-пуша откат сложнее: потребуется восстановление из серверной резервной копии или координированная работа всех участников.

## Критерии приёмки миграции

- Все целевые файлы в истории заменены указателями LFS (проверяется git lfs ls-files и просмотр коммитов).
- CI-пайплайны не ломаются и успешно собирают артефакты.
- Команда получила инструкции и смогла синхронизировать локальные копии без потери работы.
- Размер основного репозитория снизился заметно по сравнению с бэкапом.

## Роли и чек-листы

Разработчик:
- Сделать git lfs install на рабочей машине.
- Убедиться, что .gitattributes в их ветках актуален.
- После миграции пересинхронизировать ветки по инструкции команды.

Релиз-менеджер / ведающий репозиторием:
- Оценить объёмы и подготовить .gitattributes.
- Создать резервную копию репозитория.
- Планировать окно миграции и уведомить всех.

Операции / DevOps:
- Проверить поддержку LFS на сервере (GitLab/GitHub/внешний LFS-сервер).
- Обеспечить резервное копирование LFS-данных и мониторинг трафика.

## Тесты и критерии проверки

- Клонирование тестовой ветки должно вернуть указатели, а git lfs pull — реальные файлы.
- Сравнить размер bare-репозитория до и после миграции.
- Проверить, что старые коммиты открываются в GUI (например, gitk) и большие файлы не хранятся в объектах Git.

## Ментальные модели и советы

- Думайте о LFS как о «заменителе blobs» — маленький индекс в истории + внешний store.
- Для неизменяемых, редко меняющихся больших файлов эффекта максимально: одна версия в LFS, минимум изменений.
- Для часто меняющихся бинарников подумайте о альтернативных подходах: артефактные репозитории (Artifactory, Nexus) или облачные хранилища с ссылками в репозитории.

## Когда LFS не лучшая опция (контрпримеры)

- Если ваши большие файлы очень часто меняются и вам важна дедупликация версий — хранение вне Git в специализированном артефактном репозитории может быть эффективнее.
- Если у вас строгие требования к локальному хранению всех версий в одном месте (например, офлайн-бэкап) — Git LFS добавляет отдельный слой и может усложнить бэкап.

## Безопасность, приватность и соответствие требованиям

- Данные в LFS хранятся отдельно; убедитесь, что провайдер или ваш self-hosted сервер соответствует требованиям безопасности и политике хранения данных вашей организации.
- При работе с персональными данными проверьте требования GDPR/локального законодательства: место хранения, права доступа и удаление данных.

## Краткое резюме

Git LFS полезен для оптимизации репозиториев с большими двоичными файлами: он уменьшает объём истории и ускоряет клоны, но требует планирования, квот и грамотной миграции. Перед внедрением оцените объёмы, подготовьте .gitattributes, сделайте резервную копию и согласуйте шаги с командой.

Important: всегда проверяйте актуальные лимиты и цены у вашего провайдера перед массовым подключением LFS.

---

Ключевые команды (шпаргалка):

git lfs install

git lfs track “*.dat”

git lfs ls-files

git lfs migrate import –include=”*.mp4”


Краткий чек-лист перед миграцией:
- Резервная копия репозитория
- Согласование с командой
- Тестовая миграция на отдельной ветке
- Проверка CI и интеграций

Конец статьи.