.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

Patrón	Efecto
foo.txt	Cualquier archivo llamado foo.txt en cualquier nivel del árbol
foo/	Todas las carpetas llamadas foo y su contenido, en cualquier nivel (los patrones de carpeta siempre coinciden a cualquier profundidad)
foo	Cualquier archivo O carpeta llamado foo en cualquier nivel (sin barra final)

Comodines

Patrón	Efecto
*.tmp	Todos los archivos .tmp en cualquier nivel
*.{tmp,bak,old}	Expansión de llaves: equivale a *.tmp + *.bak + *.old
foo*	Cualquier archivo o carpeta cuyo nombre empiece por foo
?ile.txt	El ? coincide con exactamente un carácter: file.txt, pile.txt, etc.
[abc].txt	Clase de caracteres: a.txt, b.txt, c.txt
**/build/	Recursivo: cualquier carpeta build/ en cualquier nivel (equivalente a build/)
Content/**/Tmp/	Recursivo en medio: cualquier carpeta Tmp/ situada en algún lugar bajo Content/
Content/**	Todo lo que hay bajo Content/, a cualquier profundidad

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, distribuida en forma binaria), incluso si una regla intentara incluirla.
2. Segmento ThirdParty: si un segmento de la ruta se llama exactamente ThirdParty, el archivo nunca se ignora. Ver Carpeta ThirdParty.
3. Prefijo de plugin permitido de oficio (el Binaries/ de un plugin instalado sin código fuente): nunca se ignora.
4. De lo contrario: la ruta se ignora si coincide con uno de los patrones del archivo.

Los tres primeros pasos son decisiones definitivas: en cuanto uno de ellos se aplica, el siguiente no se evalúa, y tus patrones no se consultan en absoluto. Por eso no se puede "contrarrestar" ninguno de ellos con una regla más precisa.

Plantilla UE5 por defecto

Esto es, línea por línea, lo que el cliente de escritorio escribe en el momento del clone en un workspace UE5. Si copias este bloque a mano en un proyecto existente, cópialo entero: las secciones «IDE» y «generación de proyecto Linux» son las que más a menudo se olvidan, y su ausencia hace que se rastreen archivos de proyecto regenerados en cada build, que entonces acaban en conflicto para todo el mundo.

# 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
*.slnx
*.xcworkspace/
*.xcodeproj/
*.code-workspace
*.suo
*.sdf
*.opensdf
*.opendb
*.ncb
*.user

# Linux project generation (GenerateProjectFiles)
Makefile
.ignore

# 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 cuyo segmento se llame ThirdParty siempre se rastrea, sea cual sea la regla que la designara. Es una convención de Unreal: ThirdParty contiene las bibliotecas precompiladas (.lib, .dll, .so, .a) que la compilación del proyecto necesita. Excluirlas rompería el build en el equipo de todos tus compañeros.

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

Aunque escribas **/lib/, *.lib o *.dll en tu .uversionignore, este archivo sigue rastreándose.

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.