.uversionignore

Введение

Файл .uversionignore в корне рабочего пространства определяет файлы и папки, которые клиент никогда не должен отслеживать, загружать или включать в коммиты. Синтаксис в стиле .gitignore (подмножество: комментарии, шаблоны папок, оканчивающиеся на /, и globs по имени/расширению), компилируется через globset. Это не полноценный gitignore: отрицание через ! и привязка не поддерживаются. Несколько правил, специфичных для Unreal Engine, описаны ниже.

Файл создаётся автоматически десктопным клиентом в момент clone с шаблоном UE5 по умолчанию. Затем вы можете отредактировать его под свой проект.

Сам файл тоже отслеживается: если вы отредактируете и закоммитите его, ваши коллеги получат ваши изменения при следующем sync. Это сделано намеренно: у всей студии одни и те же правила исключения.

Синтаксис

Одно правило на строку. Пустые строки и строки, начинающиеся с #, игнорируются (комментарии).

Базовые шаблоны

Подстановочные знаки

Без отрицания (!)

В отличие от .gitignore, uVersion не поддерживает префикс ! для повторного включения файла. Строка, начинающаяся с !, обрабатывается как буквальный шаблон, а не как исключение. Повторное отслеживание файлов внутри игнорируемой папки происходит только через автоматические правила: исключение ThirdParty и внесение в белый список Binaries/ установленных плагинов (см. ниже).

Комментарии

# Build artifacts (regénérés à chaque build, jamais à versioner)
Binaries/
Intermediate/

# в середине строки не является комментарием: он входит в состав шаблона. Только # в начале строки (после необязательных пробелов) начинает комментарий.

Приоритет правил

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

1. Зарезервированный путь Plugins/uVersion: всегда игнорируется (папка, управляемая инструментом, бинарное распространение), даже если какое-то правило попыталось бы его включить.
2. Компонент ThirdParty: если сегмент пути называется ровно ThirdParty, файл никогда не игнорируется.
3. Префикс плагина в белом списке (Binaries/ установленного плагина): никогда не игнорируется.
4. Иначе: путь игнорируется, если совпадает с шаблоном из файла.

Шаблон UE5 по умолчанию

Вот в точности то, что десктопный клиент генерирует в момент clone в рабочем пространстве UE5:

# uVersion ignore - Unreal Engine 5 defaults
# Note: Installed plugins, ThirdParty directories, and plugins with
# external library dependencies are automatically whitelisted.

# Build & intermediate (regenerated by UE5)
Binaries/
Build/
DerivedDataCache/
Intermediate/
Packages/
Saved/

# IDE / editor
.vs/
.vscode/
.idea/
.vsconfig
*.sln
*.suo
*.sdf
*.opensdf
*.opendb
*.ncb
*.user

# Build artifacts
*.pdb
*.obj
*.o
*.lib
*.dll
*.so
*.dylib
*.exe
*.exp
*.ilk
*.iobj
*.ipdb
*.pch
*.ipch
*.res
*.tlog
*.manifest

# Logs & temp
*.log
*.tmp
*.bak
*.swp

# OS files
Thumbs.db
.DS_Store
desktop.ini

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

Плагины

Зарезервированная папка Plugins/uVersion

Папка Plugins/uVersion (сам плагин uVersion) всегда игнорируется на любой глубине, и это правило имеет приоритет над всем остальным. Она управляется десктопным клиентом (бинарное распространение) и никогда не должна коммититься. Соседние папки, такие как Plugins/uVersionExtras, не затрагиваются.

uVersion также применяет умную логику для остальных плагинов, ничего не требуя писать в файле:

• Если у плагина есть "Installed": true в его .uplugin и нет папки Source/ (чисто бинарный плагин, тип Marketplace) → его Binaries/ вносятся в белый список и, следовательно, отслеживаются. Это правильно: для бинарного плагина скомпилированные .dll и есть плагин.
• Если у плагина есть папка Source/ (перекомпилируемый) или нет "Installed": true → его Binaries/ и Intermediate/ игнорируются так же, как и для основного проекта (бинарные файлы, это артефакты, регенерируемые при сборке).

Эта логика избавляет от необходимости вручную поддерживать исключения для коммерческих плагинов, загруженных из Epic Marketplace. Студия может смешивать плагины с исходниками и бинарные плагины, ничего не настраивая.

Папка ThirdParty

Любой путь, содержащий ThirdParty/, всегда отслеживается, даже если родительское правило его игнорировало бы. Это по соглашению Unreal: ThirdParty/ обычно содержит предкомпилированные библиотеки (.lib, .dll, .so, .a), которые нужны для компиляции проекта.

Plugins/MyPlugin/Source/ThirdParty/SomeLib/lib/Win64/SomeLib.lib

Даже если вы напишете **/lib/ или *.lib в своём .uversionignore, этот файл останется отслеживаемым благодаря неявному правилу ThirdParty/.

Типовые рецепты

Проект с внешними исходниками арта (Maya, Blender, ZBrush)

Если ваши исходники арта (.blend, .mb, .zpr) лежат рядом с проектом UE, вы хотите отслеживать их, но, возможно, не их кэши:

# Sources d'art (à versionner)
ArtSource/

# Mais pas les caches Blender / Maya
**/blendcache_*/
**/cache/
**/temp/
**/*.blend1
**/*.mb~

Проект с несколькими тестовыми картами, которые не нужно коммитить

# Maps de test temporaires (chacun les sien sur son disque)
Content/Maps/Test_*.umap
Content/Maps/Test_*.uasset

Отслеживать конкретный бинарник вопреки общему правилу

Поскольку отрицания ! не существует, нельзя глобально исключить *.exe/*.dll, а затем снова включить один бинарник. Вместо этого поместите свои одноразовые артефакты в игнорируемую папку (например, Intermediate/) и держите отслеживаемый инструмент вне шаблонов исключения. Альтернатива Unreal: библиотеки сборки принадлежат ThirdParty/, который всегда отслеживается автоматически.

Игнорировать личные заметки

# Chacun ses notes
notes.md
TODO.txt
.scratch/

Мультиплатформенный проект с промежуточными пакетами

# Packagés (publish via le client, pas dans le repo)
Packages/
Saved/StagedBuilds/

# Caches de cook par plateforme
Saved/Cooked/
Build/Win64/
Build/Mac/
Build/Linux/

Проверка файла

Чтобы проверить, будет ли путь проигнорирован клиентом перед коммитом, используйте CLI:

$ uversion status MaybeIgnored/File.uasset
# Si le fichier apparaît dans la sortie → il est tracké
# S'il n'apparaît pas (et qu'il existe sur disque) → il est ignoré

Или, более прямо, в режиме JSON с фильтром jq:

$ uversion status --json | jq '.files[] | select(.path == "MaybeIgnored/File.uasset")'

Частые ошибки

Завершающий слэш = папка, без слэша = неоднозначно

foo игнорирует и файл foo, и папку foo/. foo/ игнорирует только папку. Если хотите точности, ставьте завершающий слэш для папок.

Чувствительность к регистру

Шаблоны чувствительны к регистру. Content/ не совпадает с content/. Поскольку Windows нечувствителен к регистру на стороне ФС, вы можете столкнуться с тихими конфликтами, если один разработчик под Windows назовёт Content/, а другой content/. Стандартизируйте на Content/.

Без повторного включения (!)

Запись !Saved/Config/Foo.ini ничего не включает повторно: отрицание не поддерживается, строка берётся как буквальный шаблон. Чтобы сохранить подпапку, игнорируйте только исключаемые поддеревья (например, Saved/Logs/, Saved/Backup/) вместо всего Saved/.

Слишком широкие шаблоны

*.zip игнорирует любой .zip в рабочем пространстве, включая игровые ассеты, намеренно названные .zip (редко, но встречается в приключенческих играх / файлах данных). Предпочитайте более специфичные шаблоны: dist/*.zip, Releases/*.zip и т. д.

Редактирование .uversionignore не влияет на уже закоммиченные файлы

Как и в git, добавление шаблона в .uversionignore не заставляет уже отслеживаемые файлы исчезнуть. Вы должны удалить их явно через десктопный клиент (Mark for delete + checkin), если хотите убрать их из репозитория.