.uversionignore

Introducción

El archivo .uversionignore en la raíz del workspace define los archivos y carpetas que el cliente nunca debe rastrear, subir ni incluir en los commits. Sintaxis al estilo de .gitignore (un subconjunto: comentarios, patrones de carpeta terminados en /, y globs de nombre/extensión), compilada por globset. No es un gitignore completo: la negación con ! y el anclaje no están soportados. Más abajo se documentan algunas reglas específicas de Unreal Engine.

El archivo lo crea automáticamente el cliente de escritorio en el momento del clone con una plantilla UE5 por defecto. Luego puedes editarlo para adaptarlo a tu proyecto.

El archivo se rastrea a sí mismo: si lo editas y lo commiteas, tus colaboradores recibirán tus cambios en el siguiente sync. Es intencional: todo el estudio comparte las mismas reglas de exclusión.

Sintaxis

Una regla por línea. Las líneas vacías y las que empiezan por # se ignoran (comentarios).

Patrones básicos

Comodines

Sin negación (!)

A diferencia de .gitignore, uVersion no soporta el prefijo ! para volver a incluir un archivo. Una línea que empieza por ! se trata como un patrón literal, no como una excepción. Volver a rastrear archivos dentro de una carpeta ignorada solo ocurre mediante las reglas automáticas: la excepción ThirdParty y la lista blanca de los Binaries/ de los plugins instalados (ver más abajo).

Comentarios

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

Un # en medio de una línea no es un comentario: forma parte del patrón. Solo un # al inicio de la línea (tras espacios en blanco opcionales) inicia un comentario.

Precedencia de reglas

El orden de las líneas en el archivo no tiene ninguna importancia: todos los patrones se compilan en un único GlobSet y una ruta se ignora en cuanto coincide con alguno de ellos. La decisión sigue una precedencia fija, en este orden:

1. Ruta reservada Plugins/uVersion: siempre ignorada (carpeta gestionada por la herramienta, distribución binaria), incluso si una regla intentara incluirla.
2. Componente ThirdParty: si un segmento de la ruta se llama exactamente ThirdParty, el archivo nunca se ignora.
3. Prefijo de plugin en lista blanca (Binaries/ de un plugin instalado): nunca se ignora.
4. De lo contrario: la ruta se ignora si coincide con un patrón del archivo.

Plantilla UE5 por defecto

Esto es exactamente lo que genera el cliente de escritorio en el momento del clone en un workspace 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

Puedes añadir tus propias reglas a este archivo. Recuerda commitearlo para que todo el estudio tenga las mismas exclusiones.

Plugins

Carpeta reservada Plugins/uVersion

La carpeta Plugins/uVersion (el propio plugin de uVersion) siempre se ignora, a cualquier profundidad, y esta regla prevalece sobre todo lo demás. La gestiona el cliente de escritorio (distribución binaria) y nunca debe commitearse. Las carpetas vecinas como Plugins/uVersionExtras no se ven afectadas.

uVersion también aplica una lógica inteligente para los demás plugins, sin necesidad de escribir nada en el archivo:

• Si un plugin tiene "Installed": true en su .uplugin y no tiene carpeta Source/ (plugin puramente binario, tipo Marketplace) → sus Binaries/ quedan en lista blanca y, por tanto, se rastrean. Es lo correcto: para un plugin binario, las .dll compiladas son el plugin.
• Si el plugin tiene carpeta Source/ (recompilable) o no tiene "Installed": true → sus Binaries/ e Intermediate/ se ignoran igual que en el proyecto principal (los binarios son artefactos regenerados en la compilación).

Esta lógica evita tener que mantener manualmente las excepciones para los plugins comerciales descargados del Marketplace de Epic. Un estudio puede mezclar plugins de código y plugins binarios sin configurar nada.

Carpeta ThirdParty

Toda ruta que contenga ThirdParty/ siempre se rastrea, incluso si una regla superior la ignorara. Es por la convención de Unreal: ThirdParty/ suele contener bibliotecas precompiladas (.lib, .dll, .so, .a) que la compilación del proyecto necesita.

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

Aunque escribas **/lib/ o *.lib en tu .uversionignore, este archivo sigue rastreándose gracias a la regla implícita ThirdParty/.

Recetas habituales

Proyecto con arte fuente externo (Maya, Blender, ZBrush)

Si tus fuentes de arte (.blend, .mb, .zpr) viven junto al proyecto UE, querrás rastrearlas pero quizá no sus cachés:

# Sources d'art (à versionner)
ArtSource/

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

Proyecto con varios mapas de prueba que no hay que commitear

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

Rastrear un binario concreto pese a una regla genérica

Como no existe la negación !, no se puede excluir globalmente *.exe/*.dll y luego volver a incluir un binario. En su lugar, coloca tus artefactos desechables bajo una carpeta ignorada (p. ej. Intermediate/) y mantén la herramienta a rastrear fuera de los patrones de exclusión. Alternativa Unreal: las bibliotecas de compilación van en ThirdParty/, que siempre se rastrea automáticamente.

Ignorar notas personales

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

Proyecto multiplataforma con paquetes intermedios

# 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/

Probar un archivo

Para comprobar si una ruta será ignorada por el cliente antes de commitear, usa la 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é

O, más directamente, en modo JSON con un filtro jq:

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

Errores habituales

Barra final = carpeta, sin barra = ambiguo

foo ignora tanto el archivo foo como la carpeta foo/. foo/ ignora solo la carpeta. Si quieres ser preciso, pon la barra final para las carpetas.

Sensible a mayúsculas

Los patrones distinguen mayúsculas y minúsculas. Content/ no coincide con content/. Como Windows es insensible a mayúsculas del lado del FS, puedes acabar con colisiones silenciosas si un dev en Windows lo llama Content/ y otro content/. Estandariza en Content/.

Sin reinclusión (!)

Escribir !Saved/Config/Foo.ini no vuelve a incluir nada: la negación no está soportada, la línea se toma como un patrón literal. Para conservar una subcarpeta, ignora solo los subárboles a excluir (p. ej. Saved/Logs/, Saved/Backup/) en lugar de todo Saved/.

Patrones demasiado amplios

*.zip ignora todo .zip del workspace, incluidos assets de juego nombrados deliberadamente .zip (raro, pero ocurre en juegos de aventura / archivos de datos). Prefiere patrones más específicos: dist/*.zip, Releases/*.zip, etc.

Editar .uversionignore no afecta a los archivos ya commiteados

Como en git, añadir un patrón a .uversionignore no hace desaparecer los archivos ya rastreados. Debes eliminarlos explícitamente mediante el cliente de escritorio (Mark for delete + checkin) si quieres quitarlos del repo.