Git LFS

Git LFS (Large File Storage) — расширение для Git, которое позволяет хранить бинарные файлы — картинки, PDF, Word или Excel документы, отдельно от репозитория. Они выгружаются в S3, предоставляемое git-хранилищем. Это позволяет ускорить клонирование и синхронизацию, а также уменьшить размер репозитория.

Подключение LFS

Каталог должен быть предварительно опубликован в одном из поддерживаемых Git-хранилищ:

Далее, настройте какие файлы LFS будет отслеживать. Вы можете как добавить их вручную, так и воспользоваться автоматической настройкой — это добавит частоиспользуемые файлы в список.

Файл .gitattributes в корне репозитория определяет, какие файлы будут отслеживаться в LFS. Их необходимо указывать в виде glob-паттернов.

При сохранении, в этот файл запишутся указанные паттерны с атрибутом filter=lfs — он и является маркером для Git LFS. При необходимости этот файл можно подкорректировать вручную для добавления собственных атрибутов.

*.png filter=lfs
*.pdf filter=lfs
*.docx filter=lfs
*.xlsx filter=lfs
*.pptx filter=lfs

После этого указанные файлы начнут отслеживаться и будут отмечены значком LFS в списке просмотра изменений.

Git-хранилища также по-особенному отображают такие файлы. К примеру, так это выглядит в GitLab.

Ленивая подгрузка ресурсов

По умолчанию, приложение-редактор не загружает LFS-объекты при клонировании репозитория. Вместо этого, они подгружаются при открытии статьи. Это позволяет сократить время клонирования репозитория и уменьшить его локальный размер.

При необходимости вы можете включить автоматическое скачивание всех LFS-объектов для текущей ревизии в Действия с каталогом → Инструменты → Автоматическая загрузка LFS. Первая синхронизация может занять продолжительное время в больших репозиториях.

Миграция ресурсов существующего каталога в LFS

В давно существующем каталоге подключение LFS не решит проблему его размера. Старые ресурсы останутся в истории репозитория.

Для их миграции вы можете воспользоваться git-lfs. Это деструктивное действие, которое изменит историю всего репозитория. Перед выполнением рекомендуется сделать резервную копию.

# Установка git-lfs
git lfs install

# Получить все ветки, в ином случае перезапишутся только существующие локально
git fetch --all

# Подсчитает и отобразит суммарный размер всех файлов по его типу
git lfs migrate info --everything --pointers=ignore

# Вы можете указать свои типы файлов
git lfs migrate import --everything --include "*.png,*.mp4,*.gif"

# Запушит изменения и перезапишет историю всех референсов
git push --force --all

Известные ограничения

В приложении не используется оригинальное расширение git-lfs. Оно частично реализует его спецификацию.

Не реализовано: