Проект Godot 4.4 в Git: исходники, UID и импортный кэш
В репозиторий Godot нужно сохранять исходный проект и значимые метаданные ресурсов, но не весь автоматически созданный рабочий кэш. Для Godot 4.4 особенно важно не перепутать каталог .godot/ с соседними файлами .uid: у них разные роли и правила хранения.
Инструкция привязана к Godot 4.4. Правила для Godot 3.x и ранних выпусков 4.x отличаются. Это не инструкция по удалению «всего лишнего» и не замена резервной копии перед миграцией проекта.
Начните с метаданных контроля версий
Руководство Godot по VCS описывает генерацию .gitignore и .gitattributes при создании проекта или через Project → Version Control → Generate Version Control Metadata. Используйте вариант для Git и просмотрите результат перед коммитом.
.gitignore управляет исключениями, а .gitattributes помогает согласовать представление текстовых файлов, в частности окончания строк. Не заменяйте их случайным шаблоном для Unity только потому, что оба приложения — игровые движки.
Перед первым коммитом убедитесь, что в проекте есть project.godot, сцены, скрипты и исходные изображения, звуки и другие используемые ресурсы. Настройка игнорирования полезна только вместе с проверкой того, что нужные файлы действительно включены.
Что сохранять, а что исключать
Для Godot 4.1 и новее официальное руководство рекомендует исключать .godot/ и генерируемые *.translation. При этом исходные таблицы локализации или другие авторские файлы не становятся ненужными только из-за сходного названия.
| Файл или каталог | Роль и решение для обычного проекта 4.4 |
|---|---|
project.godot, сцены, скрипты, исходные ресурсы |
Основа проекта; сохранять |
.godot/ |
Автоматические данные редактора и импорта; исключать из обычного репозитория |
*.uid рядом со скриптами и шейдерами |
Стабильные идентификаторы; сохранять вместе с соответствующими файлами |
.import рядом с исходным ресурсом |
Метаданные импорта; не путать с кэш-каталогом и не исключать маской без разбора |
export_presets.cfg |
Настройки экспорта; проверить содержимое и сохранять для воспроизводимости |
.godot/export_credentials.cfg |
Конфиденциальные параметры экспорта; не публиковать |
Базовые исключения для указанной версии выглядят так:
.godot/
*.translation
Это не исчерпывающая политика для всех плагинов. Дополнительные ключи, локальные настройки и крупные внешние исходники требуют своего разбора. Не используйте широкую маску *.uid или *.import как средство уменьшить число файлов в коммите.
Почему UID — не одноразовый кэш
В официальном разборе перехода к Godot 4.4 описаны соседние файлы идентификаторов скриптов и шейдеров, например player.gd.uid. Рекомендация авторов — включать .uid в контроль версий и переносить его вместе с соответствующим исходником при внешнем перемещении.
Это историческая публикация января 2025 года о механизме 4.4, а не утверждение, что 4.4 сейчас последний выпуск. У импортируемых ресурсов UID может храниться в метаданных .import; у собственных сцен и ресурсов — в заголовках. Одно правило «все метаданные можно удалить» здесь неприменимо.
После обновления старого проекта авторы рекомендуют пересохранить сцены и ресурсы для добавления недостающих ссылок UID. Делайте это отдельным понятным изменением и проверяйте diff: так новые идентификаторы не смешаются с большой переработкой игрового кода.
Проверьте первый коммит, а не только шаблон
Перед добавлением файлов выполните git status --short и просмотрите список. В нём не должно неожиданно появляться содержимое .godot/, личные ключи или готовые архивы сборок. При этом новые сцены, ресурсы и соответствующие .uid не должны теряться.
Важно: правила Git не перестают отслеживать уже добавленные файлы автоматически. Если кэш ранее попал в индекс, одно редактирование .gitignore не исправит историю и состав отслеживаемого дерева. Разберите это отдельно, сохранив рабочие данные; не начинайте с удаления всего каталога проекта.
Посмотрите diff текстовых сцен и настроек. Изменение параметра импорта может быть нужным результатом работы, а не шумом. И наоборот, секрет в текстовом файле не становится безопасным только потому, что Git показывает его обычными строками.
Самая полезная проверка — чистая копия
Клонируйте сохранённое состояние в отдельный каталог, не поверх текущего проекта. Откройте его той же версией Godot, дождитесь импорта, запустите основную сцену и проверьте несколько переходов между ресурсами.
Затем выполните экспорт из пресета, восстановив необходимые credentials безопасно и не добавляя их в публичный коммит. Если проект работает только в исходной рабочей папке, найдите неучтённую зависимость: перенос старого кэша не доказывает полноту репозитория.
Повторный импорт чистой копии ожидаем и не равен регрессии скорости игрового кадра. Для последнего используйте Profiler Godot.
FAQ
Можно ли удалить все .uid, чтобы они появились заново?
Не используйте это как обычную уборку. В 4.4 идентификаторы сохраняют связи, а официальная рекомендация — коммитить их вместе с исходниками.
Почему .godot/ всё ещё виден после добавления в ignore?
Возможно, его файлы уже отслеживаются. Проверьте индекс и историю; ignore не отменяет прежнее добавление.
Достаточно сохранить только .tscn и .gd?
Нет. Нужны настройки проекта, исходные ресурсы и соответствующие метаданные. Полноту подтверждает чистая копия и запуск, а не только расширения двух типов файлов.