Git LFS

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

Git LFS работает незаметно для пользователя: в рабочей копии вы увидите только фактическое содержимое файла. Поэтому при использовании Git LFS вы можете сохранить существующий рабочий процесс Git, в рамках которого нужно выполнять команду git checkout, редактировать файл, а затем выполнять команды git add и git commit. Команды git clone и git pull будут выполняться значительно быстрее, потому что при переключении на конкретный коммит в Git LFS загружаются только те версии крупных файлов, на которые он ссылается, а не все существующие версии.

Для работы с Git LFS вам понадобится инструмент хостинга с поддержкой Git LFS, такой как Bitbucket Cloud или Bitbucket Data Center. Пользователям репозитория потребуется установить клиент командной строки Git LFS или клиент c графическим интерфейсом и поддержкой Git LFS, например Sourcetree. Кстати, в проекте Git LFS активно участвует Стив Стритинг, разработчик Atlassian и автор Sourcetree, поэтому Sourcetree и Git LFS хорошо работают вместе.

1. Существует три простых способа установки Git LFS:

a. Установка с помощью привычного менеджера пакетов. Пакеты git-lfs можно установить с помощью Homebrew, MacPorts, dnf или packagecloud.

b. Загрузка и установка Git LFS с сайта проекта.

c. Установка Sourcetree — бесплатного клиента Git с графическим интерфейсом, в комплект поставки которого входит Git LFS.

2. Когда в пути появится git-lfs, выполните команду git lfs install для инициализации Git LFS (если вы установили Sourcetree, этот шаг можно пропустить):

Команду git lfs install нужно будет выполнить только один раз. После инициализации в системе хранилище Git LFS будет автоматически загружаться при клонировании репозитория, содержащего контент Git LFS.

Чтобы создать новый репозиторий с поддержкой Git LFS, после создания репозитория нужно выполнить команду git lfs install:

При этом в репозитории появится специальный хук Git pre-push, который будет передавать файлы Git LFS на сервер при выполнении команды git push.

Git LFS включается автоматически для всех репозиториев Bitbucket Cloud. Для версии Bitbucket Data Center потребуется включить Git LFS в настройках репозитория:

После инициализации хранилища Git LFS для репозитория вы можете указать, какие файлы нужно отслеживать, с помощью команды git lfs track.

После установки Git LFS репозиторий Git LFS можно клонировать обычным способом с помощью команды git clone. По завершении клонирования система Git переключится на ветку по умолчанию (обычно это ветка main), при этом все файлы Git LFS, необходимые для переключения, загрузятся автоматически. Вот несколько примеров.

В этом репозитории находятся четыре файла PNG, которые отслеживает Git LFS. При выполнении команды git clone последовательно загружаются файлы Git LFS по мере того, как из репозитория загружаются соответствующие им файлы указателей.

При клонировании репозитория с большим количеством файлов LFS заданная в явном виде команда git lfs clone заметно улучшит производительность:

Вместо того чтобы загружать файлы Git LFS по отдельности, команда git lfs clone дожидается завершения переключения, а затем загружает все необходимые файлы Git LFS одним пакетом. При этом используется параллельная загрузка, а также резко сокращается количество HTTP-запросов и порожденных процессов (что особенно важно для повышения производительности в Windows).

Как и при клонировании, для получения данных из репозитория Git LFS можно использовать обычную команду git pull. Все необходимые файлы Git LFS будут автоматически загружены в процессе переключения после выполнения команды pull:

Чтобы извлечь содержимое Git LFS, не обязательно задавать команду в явном виде. Однако если произойдет непредвиденная ошибка переключения, вы сможете загрузить любой недостающий контент Git LFS для текущего коммита командой git lfs pull:

Подобно git lfs clone, команда git lfs pull загружает файлы Git LFS одним пакетом. Если известно, что с момента последнего получения было изменено большое количество файлов, можно отключить автоматическую загрузку файлов Git LFS во время операции переключения и затем загрузить контент из Git LFS одним пакетом, задав в явном виде команду git lfs pull. Для этого нужно переопределить конфигурацию Git, указав параметр -c при вызове команды git pull:

Чтобы не вводить длинный текст, можно создать простой псевдоним Git для получения данных из Git и Git LFS одним пакетом:

Это позволит значительно повысить производительность при загрузке большого количества файлов Git LFS (особенно в Windows).

При добавлении в репозиторий крупных файлов нового типа нужно сообщить Git LFS, что их требуется отслеживать, указав в команде git lfs track шаблон имени файла:

Обратите внимание на важную деталь: сегмент "*.ogg" заключен в кавычки. Если не поставить кавычки, оболочка развернет этот шаблон и создаст отдельную запись для каждого файла с расширением .ogg в текущем каталоге:

Git LFS поддерживает те же шаблоны, что и .gitignore, например:

Шаблоны задаются относительно каталога, из которого выполняется команда git lfs track. Чтобы упростить задачу, лучше всего выполнять команду git lfs track из корневого каталога репозитория. Обратите внимание: в отличие от .gitignore, Git LFS не поддерживает отрицательные шаблоны.

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

Для удобства технического обслуживания проще всего хранить все шаблоны имен Git LFS в одном файле .gitattributes и всегда выполнять команду git lfs track из корневого каталога своего репозитория. В любом случае, вы можете отобразить список всех шаблонов, которые в настоящее время отслеживаются Git LFS (и файлов .gitattributes, в которых они определены), вызвав команду git lfs track без аргументов:

Чтобы прекратить отслеживание определенного шаблона имен в Git LFS, просто удалите соответствующую строку из файла .gitattributes или выполните команду git lfs untrack:

После выполнения команды git lfs untrack вам снова нужно будет самостоятельно выполнить коммит изменений в файле .gitattributes.

Вы можете выполнять коммиты и отправлять изменения в репозиторий Git LFS обычным способом. Если вы выполнили коммит изменений в файлах, которые отслеживаются Git LFS, то увидите дополнительные выходные данные команды git push при передаче контента Git LFS на сервер:

Если передача файлов LFS по какой-то причине не удалась, отправка будет прервана, после чего вы сможете безопасно повторить попытку. Как и Git, хранилище Git LFS является контентно-адресуемым: контент хранится с ключом, который представляет собой хеш SHA-256 самого контента. Это означает, что всегда можно безопасно повторить попытку переноса файлов Git LFS на сервер; вы не сможете случайно заменить содержимое файла Git LFS неправильной версией.

Для переноса репозитория Git LFS на другой хостинг можно использовать комбинацию команд git lfs fetch и git lfs push с параметром --all.

Например, вот так можно перенести весь репозиторий Git и Git LFS с удаленного сервера github на удаленный сервер bitbucket 😉 :

Как правило, Git LFS загружает только файлы, необходимые для коммитов, на которые вы переключаетесь локально. Однако вы можете заставить Git LFS загрузить дополнительный контент для других недавно измененных веток с помощью команды git lfs fetch --recent:

Эту команду удобно использовать для пакетной загрузки нового контента Git LFS, пока вы обедаете, а также если вы планируете просмотреть работу коллег, но не сможете загрузить контент позже из-за ограниченной доступности Интернета. Например, вы можете выполнить команду git lfs fetch --recent, перед тем как сесть на самолет.

В Git LFS недавними считаются ветки или теги, которые содержат коммит, выполненный менее семи дней назад. Чтобы настроить продолжительность этого периода, измените количество дней в свойстве lfs.fetchrecentrefsdays:

По умолчанию команда git lfs fetch --recent загружает контент Git LFS только для коммита, который находится в конце недавней ветки или тега.

Однако можно настроить Git LFS так, чтобы загружался контент и для более ранних коммитов в недавних ветках и тегах. Для этого нужно сконфигурировать свойство lfs.fetchrecentcommitsdays:

Используйте эту настройку с осторожностью: при быстром продвижении веток она может привести к загрузке огромного количества данных. Однако эта возможность полезна, если требуется просмотреть промежуточные изменения в ветке, перенести коммиты из одной ветки в другую или перезаписать историю.

Как описано в разделе Перенос репозитория Git LFS на другой хостинг, вы также можете извлечь весь контент Git LFS для своего репозитория командой git lfs fetch --all:

Удалить файлы из локального кэша Git LFS можно с помощью команды git lfs prune:

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

• в текущем коммите;
• в коммите, который еще не отправлен (в репозиторий origin или в репозиторий, заданный в свойстве lfs.pruneremotetocheck);
• в недавнем коммите.

По умолчанию недавним считается любой коммит, созданный за последние десять дней. Это значение рассчитывается путем сложения. Суммируются:

• значение свойства lfs.fetchrecentrefsdays, рассмотренное в разделе Извлечение дополнительной истории Git LFS (по умолчанию равно семи);
• значение свойства lfs.pruneoffsetdays (по умолчанию равно трем).

Чтобы сохранить контент Git LFS за более длительный период, можно настроить смещение удаления:

В отличие от встроенной в Git сборки мусора, контент Git LFS не удаляется автоматически, поэтому для уменьшения размера локального репозитория полезно регулярно выполнять команду git lfs prune.

Проверить, какой результат даст операция удаления, можно с помощью команды git lfs prune --dry-run:

А чтобы узнать, какие именно объекты Git LFS будут удалены, выполните команду git lfs prune --verbose --dry-run:

Длинные шестнадцатеричные строки, которые выводятся в режиме --verbose, — это хэши SHA-256 удаляемых объектов Git LFS (их также называют идентификаторами объектов или OID). Подробнее об удаляемых объектах можно узнать с помощью методов, описанных в разделе Поиск путей или коммитов, ссылающихся на объект Git LFS.

Для лучшей безопасности можно использовать параметр --verify-remote, чтобы убедиться, что в удаленном хранилище есть копии объектов Git LFS, прежде чем удалять эти объекты:

Это существенно замедляет процесс удаления, но при этом вы будете точно знать, что все удаленные объекты можно восстановить с сервера. Кроме того, можно сделать так, чтобы параметр --verify-remote работал в системе постоянно. Для этого настройте свойство lfs.pruneverifyremotealways на глобальном уровне:

Или же можно включить удаленную проверку только для репозитория контекста, опустив параметр --global в приведенной выше команде.

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

В Bitbucket Cloud просмотреть и удалить файлы Git LFS можно в разделе Git LFS настроек репозитория:

Обратите внимание, что каждый файл в Git LFS индексируется с помощью своего идентификатора OID SHA-256, в то время как пути, указывающие на файл, не отображаются в пользовательском интерфейсе. Это связано с тем, что в разных коммитах может быть много разных путей, указывающих на один объект, поэтому поиск по ним будет очень медленным.

Определить, что на самом деле содержится в файле Git LFS, можно тремя способами:

• Посмотреть на изображение для предварительного просмотра и на тип файла в левом столбце пользовательского интерфейса Bitbucket Git LFS.
• Загрузить файл с помощью ссылки в правом столбце пользовательского интерфейса Bitbucket Git LFS. Найти коммиты, которые ссылаются на идентификатор OID SHA-256 объекта Git LFS, как описано в следующем разделе.

Если у вас есть идентификатор OID SHA-256 в Git LFS, вы можете определить, какие коммиты на него ссылаются, с помощью команды git log --all -p -S :

Это заклинание с применением команды git log генерирует исправление (-p) из коммитов во всех ветках (--all), которые добавляют или удаляют строку (-S), содержащую указанный текст (идентификатор OID SHA-256 в Git LFS).

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

Если вы предполагаете, что конкретный объект Git LFS находится в коммите, на который указывает HEAD, или в какой-то определенной ветке, можно воспользоваться командой git grep, чтобы найти путь к файлу, который на него ссылается:

HEAD или power-ups можно заменить любой ссылкой, коммитом или деревом, которые содержат объект Git LFS.

Иногда бывает нужно загрузить только часть доступного контента Git LFS для конкретного коммита. Так, при настройке сборки CI для выполнения модульных тестов вам может потребоваться загрузить только исходный код, исключив тяжеловесные файлы, которые не нужны для сборки кода.

Вы можете исключить подкаталог или файлы с определенным шаблоном имен с помощью команды git lfs fetch -X (или --exclude):

И наоборот, вы можете включить только конкретный подкаталог или файлы с определенным шаблоном имен. Например, инженер звукозаписи может извлечь только файлы с расширениями ogg и wav с помощью команды git lfs fetch -I (или --include):

Если использовать параметры включения и исключения в одной команде, будут извлечены только файлы, которые соответствуют шаблону включения и не соответствуют шаблону исключения. Например, вы можете извлечь все файлы из каталога Assets, за исключением файлов GIF, с помощью следующей команды:

С параметрами включения и исключения можно применять те же шаблоны имен, что и с командой git lfs track и файлом .gitignore. Эти шаблоны можно сделать постоянными для конкретного репозитория, настроив свойства конфигурации lfs.fetchinclude и lfs.fetchexclude:

Эти настройки можно применить ко всем репозиториям в системе, если добавить параметр --global.

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

Чтобы воспользоваться функцией блокировки файлов в LFS, нужно сначала сообщить системе Git, какой тип файлов можно блокировать. В приведенном ниже примере в команду git lfs track добавлен флаг --lockable. С помощью такой команды вы можете сохранить PSD-файлы в LFS и пометить их как блокируемые.

Затем нужно добавить в файл .gitattributes следующую строку:

При подготовке к внесению изменений в файл LFS необходимо использовать команду блокировки, чтобы зарегистрировать файл на сервере Git в качестве заблокированного.

Если блокировка файла больше не требуется, ее можно снять с помощью команды разблокировки Git LFS.

Как и в случае с командой git push, блокировку файлов Git LFS можно переопределить с помощью флага --force. Используйте флаг --force, только если вы уверены в своих действиях.