Лимиты GitHub на размер файлов и репозитория: как работать с большими бинарниками через Git LFS
GitHub жёстко ограничивает размер single-файла и общий объём репозитория. Если в проекте есть дампы баз, PDF-отчёты или собранные ассеты, обычный git push рано или поздно упрётся в отказ. Разберём актуальные лимиты, настройку Git LFS и миграцию существующей истории без потери данных.
Какие ограничения действуют сейчас
GitHub не запрещает хранить бинарные файлы, но вводит жёсткие пороги. Если файл превышает 50 МБ, при пуше вы получите предупреждение. Начиная со 100 МБ push отклоняется полностью — объект не попадает в удалённый репозиторий. Это касается именно размера отдельного файла в коммите, а не размера всего коммита.
Параллельно действует рекомендация держать репозиторий в пределах 1 ГБ. Жёсткого технического отказа на 1 ГБ нет, но при 5 ГБ и выше поддержка GitHub может прислать уведомление с просьбой сократить объём. Для проектов с регулярными артефактами это критично уже после нескольких релизов.
| Порог | Поведение GitHub | Что делать |
|---|---|---|
| 50 МБ | Warning при push | Проверить, нужен ли файл именно в git-истории |
| 100 МБ | Reject при push | Подключить Git LFS или вынести артефакт во внешнее хранилище |
| ~1 ГБ | Рекомендованный предел репозитория | Очистить историю, удалить старые бинарники |
| 5 ГБ+ | Возможна блокировка записи | Разгрузить историю или перенести крупные объекты в LFS |
В PHP-проектах чаще всего в лимиты упираются дампы SQL для локальной разработки, сгенерированные PDF/Excel-отчёты для тестов и vendor-пакеты, ошибочно добавленные в индекс. Размер .git при этом растёт нелинейно: каждая версия бинарника сохраняется целиком, а не как дельта.
Почему Git не подходит для больших бинарников
Git создавался для текстовых файлов. Каждый новый коммит с изменённым бинарником добавляет в историю полную копию файла. Десять правок PDF на 25 МБ — это 250 МБ в истории, даже если в рабочей копии лежит одна актуальная версия. Клонирование такого репозитория превращается в загрузку всех когда-либо существовавших состояний.
Git LFS решает проблему иначе. Вместо самого файла в объектах git хранится маленький текстовый указатель, а сам бинарник лежит на отдельном LFS-сервере. При клонировании репозиторий скачивается быстро, а бинарные ассеты подтягиваются только при checkout нужной версии. Для CI/CD это означает экономию трафика и времени на сборке.
Установка Git LFS
В большинстве дистрибутивов пакет доступен из коробки. После установки нужно один раз инициализировать расширение для текущего пользователя системы — без этого хуки не будут отрабатывать при коммитах.
# Debian/Ubuntu
sudo apt install git-lfs
# macOS через Homebrew
brew install git-lfs
# Инициализация глобального конфига
git lfs installПроверить корректность установки можно через версию и статус. Если в выводе нет ошибок, можно переходить к настройке отслеживания.
git lfs version
git lfs envОтслеживание файлов через .gitattributes
Правила LFS описываются в файле .gitattributes в корне репозитория. Он коммитится как обычный файл, поэтому правила применяются для всех участников проекта. Шаблоны работают по аналогии с .gitignore.
# Начать отслеживать PDF и SQL-дампы
git lfs track "*.pdf"
git lfs track "*.sql"
# Можно указать конкретный файл
git lfs track "tests/fixtures/large-export.xlsx"После выполнения команды файл .gitattributes будет содержать строки вида:
*.pdf filter=lfs diff=lfs merge=lfs -text
*.sql filter=lfs diff=lfs merge=lfs -text
tests/fixtures/large-export.xlsx filter=lfs diff=lfs merge=lfs -textФлаг -text указывает, что это бинарные данные и git не должен пытаться мержить их как текст. Это защищает от автоматических конфликтов при слиянии веток.
# Не забыть закоммитить сам .gitattributes
git add .gitattributes
git commit -m "Add LFS tracking rules for binary files"Перенос уже закоммиченных больших файлов
Самая сложная часть — миграция репозитория, где большие файлы уже находятся в истории. Просто добавить правила отслеживания недостаточно: старые объекты останутся в .git, и размер клона не уменьшится. Для переноса используется команда git lfs migrate.
Перед миграцией убедитесь, что рабочая копия чистая и все изменения закоммичены. Также стоит договориться с командой о временной заморозке пушей — после переписывания истории всем придётся переклонировать репозиторий.
# Посмотреть, сколько места занимают конкретные расширения в истории
git lfs migrate info --everything --include="*.pdf,*.sql"
# Выполнить миграцию: переписать историю и вынести бинарники в LFS
git lfs migrate import --everything --include="*.pdf,*.sql"Флаг --everything означает обработку всех веток и тегов, не только текущей. Без него перенос затронет только активную ветку, что создаст рассинхрон между историей. После миграции push будет принудительным:
git push origin --force --all
git push origin --force --tagsВажно: GitHub хранит LFS-объекты отдельно, и для бесплатных аккаунтов действует квота на объём и трафик. Перед миграцией убедитесь, что суммарный размер бинарников не превысит лимиты тарифного плана.
Что это значит для PHP-разработчика
В PHP-проектах Git LFS чаще всего нужен не для исходников, а для окружения: дампы тестовых баз, фикстуры с изображениями, PDF-отчёты для проверки парсеров, собранные JS/CSS-бандлы в монорепозиториях. Исходный код на PHP остаётся в обычном git — это текст, он хорошо сжимается и дельтируется.
При подключении LFS в проекте на PHP 8.3+ стоит сразу прописать расширения для типовых артефактов:
git lfs track "storage/tests/*.pdf"
git lfs track "database/dumps/*.sql"
git lfs track "public/build/*.js"
git lfs track "public/build/*.css"Если part проекта генерирует отчёты через PHP-скрипт, логично исключить их из git-индекса и складывать в отдельное хранилище или volume. В .gitignore это выглядит так:
/storage/generated/
/reports/*.pdf
/tmp/exports/Для CI/CD важно помнить, что при клонировании обычный git clone не выкачивает LFS-объекты автоматически во всех окружениях. Нужно явно выполнить git lfs pull после клонирования либо настроить конвейер на использование GIT_LFS_SKIP_SMUDGE=1, если бинарники для конкретного шага не нужны.
# В CI-пайплайне после клонирования
git lfs pull
# Или пропустить загрузку LFS-файлов, если шаг работает только с исходниками
GIT_LFS_SKIP_SMUDGE=1 git clone --depth 1 git@github.com:org/repo.gitАльтернативы Git LFS
LFS — не единственный вариант. Для крупных бинарных артефактов иногда проще использовать внешнее объектное хранилище: S3-совместимый сервис, GitHub Releases с прикреплёнными ассетами или внутренний артефакторий. PHP-проекты, которые собирают Docker-образы, обычно вообще не кладут их в репозиторий — для этого есть container registry.
Git LFS уместен, когда бинарные файлы должны быть связаны с конкретной версией кода и участвовать в checkout. Если файл нужен только на этапе деплоя — лучше отдать его в CI-хранилище или загружать по прямой ссылке из скрипта сборки.
Практичный чек-лист
- Проверьте текущий размер репозитория:
git count-objects -vHиdu -sh .git. - Найдите самые тяжёлые файлы в истории:
git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectsize) %(rest)' | awk '$1=="blob" && $2>1048576 {print $2, $3}' | sort -rn | head -20. - Установите
git-lfsи выполнитеgit lfs installдля каждого разработчика. - Пропишите правила отслеживания для расширений, которые точно бинарные:
*.pdf,*.sql,*.xlsx,*.jpg. - Закоммитьте
.gitattributesотдельным коммитом, чтобы изменения правил были атомарными. - Если большие файлы уже в истории — выполните
git lfs migrate import --everythingи предупредите команду о force-push. - Настройте CI: добавьте
git lfs pullпосле клонирования либо осознанно пропустите загрузку LFS-объектов. - Регулярно проверяйте квоту LFS в настройках репозитория на GitHub, чтобы не упереться в лимит трафика.
Частые вопросы
Что будет, если запушить файл больше 100 МБ на GitHub без LFS?
Push будет отклонён с ошибкой. Файл не попадёт в удалённый репозиторий, пока вы не удалите его из коммита или не перенесёте в Git LFS.
Можно ли использовать Git LFS для PHP-исходников?
Технически да, но практического смысла нет. PHP-файлы — это текст, который хорошо сжимается и дельтируется обычным git. LFS нужен для бинарников: дампов, PDF, изображений, собранных ассетов.
Как проверить, какие файлы уже отслеживаются через LFS?
Выполните <code>git lfs ls-files</code> в корне репозитория. Команда покажет все файлы, которые в текущей рабочей копии обрабатываются как LFS-объекты.
Как уменьшить размер существующего репозитория без LFS?
Можно переписать историю командой <code>git filter-repo</code> или <code>git gc --aggressive --prune=now</code>, но это переписывание истории и требует force-push. Более безопасный путь — миграция на LFS через <code>git lfs migrate import</code>.