.uversionignore

Introdução

O arquivo .uversionignore na raiz do workspace define os arquivos e pastas que o cliente nunca deve rastrear, enviar ou incluir nos commits. Sintaxe no estilo .gitignore (um subconjunto: comentários, padrões de pasta terminados em / e globs de nome/extensão), compilada pelo globset. Não é um gitignore completo: a negação com ! e a ancoragem não são suportadas. Algumas regras específicas do Unreal Engine estão documentadas mais abaixo.

O arquivo é criado automaticamente pelo cliente desktop no momento do clone com um template UE5 padrão. Você pode editá-lo depois para adaptá-lo ao seu projeto.

O arquivo é ele próprio rastreado: se você editá-lo e commitá-lo, seus colaboradores recebem suas alterações no próximo sync. É intencional: todo o estúdio tem as mesmas regras de exclusão.

Sintaxe

Uma regra por linha. Linhas vazias e linhas que começam com # são ignoradas (comentários).

Padrões básicos

Curingas

Sem negação (!)

Ao contrário do .gitignore, o uVersion não suporta o prefixo ! para reincluir um arquivo. Uma linha que começa com ! é tratada como um padrão literal, não como uma exceção. Rastrear novamente arquivos dentro de uma pasta ignorada só acontece por meio das regras automáticas: a exceção ThirdParty e a lista branca dos Binaries/ de plugins instalados (veja abaixo).

Comentários

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

Um # no meio de uma linha não é um comentário: faz parte do padrão. Apenas um # no início da linha (após espaços em branco opcionais) inicia um comentário.

Precedência das regras

A ordem das linhas no arquivo não tem nenhuma importância: todos os padrões são compilados em um único GlobSet e um caminho é ignorado assim que corresponde a qualquer um deles. A decisão segue uma precedência fixa, nesta ordem:

1. Caminho reservado Plugins/uVersion: sempre ignorado (pasta gerenciada pela ferramenta, distribuição binária), mesmo que uma regra tentasse incluí-lo.
2. Componente ThirdParty: se um segmento do caminho se chama exatamente ThirdParty, o arquivo nunca é ignorado.
3. Prefixo de plugin na lista branca (Binaries/ de um plugin instalado): nunca é ignorado.
4. Caso contrário: o caminho é ignorado se corresponder a um padrão do arquivo.

Template UE5 padrão

Aqui está exatamente o que o cliente desktop gera no momento do clone em um 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

Você pode adicionar suas próprias regras a este arquivo. Lembre-se de commitá-lo para que todo o estúdio tenha as mesmas exclusões.

Plugins

Pasta reservada Plugins/uVersion

A pasta Plugins/uVersion (o próprio plugin do uVersion) é sempre ignorada, em qualquer profundidade, e essa regra prevalece sobre todo o resto. Ela é gerenciada pelo cliente desktop (distribuição binária) e nunca deve ser commitada. Pastas vizinhas como Plugins/uVersionExtras não são afetadas.

O uVersion também aplica uma lógica inteligente para os outros plugins, sem nada a escrever no arquivo:

• Se um plugin tem "Installed": true em seu .uplugin e não tem pasta Source/ (plugin puramente binário, tipo Marketplace) → seus Binaries/ ficam na lista branca e, portanto, são rastreados. É o correto: para um plugin binário, as .dll compiladas são o plugin.
• Se o plugin tem pasta Source/ (recompilável) ou não tem "Installed": true → seus Binaries/ e Intermediate/ são ignorados como no projeto principal (os binários são artefatos regenerados no build).

Essa lógica evita ter que manter manualmente as exceções para os plugins comerciais baixados do Marketplace da Epic. Um estúdio pode misturar plugins de código e plugins binários sem configurar nada.

Pasta ThirdParty

Qualquer caminho que contenha ThirdParty/ é sempre rastreado, mesmo que uma regra superior o ignorasse. É por convenção do Unreal: ThirdParty/ normalmente contém libs pré-compiladas (.lib, .dll, .so, .a) das quais a compilação do projeto precisa.

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

Mesmo que você escreva **/lib/ ou *.lib no seu .uversionignore, esse arquivo continua rastreado graças à regra implícita ThirdParty/.

Receitas comuns

Projeto com arte fonte externa (Maya, Blender, ZBrush)

Se suas fontes de arte (.blend, .mb, .zpr) ficam ao lado do projeto UE, você quer rastreá-las, mas talvez não seus caches:

# Sources d'art (à versionner)
ArtSource/

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

Projeto com vários mapas de teste que não devem ser commitados

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

Rastrear um binário específico apesar de uma regra genérica

Como a negação ! não existe, não é possível excluir globalmente *.exe/*.dll e depois reincluir um binário. Em vez disso, coloque seus artefatos descartáveis sob uma pasta ignorada (por ex. Intermediate/) e mantenha a ferramenta a rastrear fora dos padrões de exclusão. Alternativa Unreal: as libs de build pertencem a ThirdParty/, que é sempre rastreado automaticamente.

Ignorar notas pessoais

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

Projeto multiplataforma com pacotes intermediários

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

Testar um arquivo

Para verificar se um caminho será ignorado pelo cliente antes de commitar, use a 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é

Ou, mais diretamente, em modo JSON com um filtro jq:

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

Armadilhas comuns

Barra final = pasta, sem barra = ambíguo

foo ignora tanto o arquivo foo quanto a pasta foo/. foo/ ignora apenas a pasta. Se quiser ser preciso, coloque a barra final para as pastas.

Sensível a maiúsculas

Os padrões diferenciam maiúsculas de minúsculas. Content/ não corresponde a content/. Como o Windows é insensível a maiúsculas do lado do FS, você pode acabar com colisões silenciosas se um dev no Windows nomear Content/ e outro content/. Padronize em Content/.

Sem reinclusão (!)

Escrever !Saved/Config/Foo.ini não reinclui nada: a negação não é suportada, a linha é tomada como um padrão literal. Para manter uma subpasta, ignore apenas as subárvores a excluir (por ex. Saved/Logs/, Saved/Backup/) em vez de todo o Saved/.

Padrões amplos demais

*.zip ignora todo .zip do workspace, inclusive assets de jogo nomeados deliberadamente .zip (raro, mas acontece em jogos de aventura / arquivos de dados). Prefira padrões mais específicos: dist/*.zip, Releases/*.zip, etc.

Editar .uversionignore não afeta os arquivos já commitados

Como no git, adicionar um padrão ao .uversionignore não faz os arquivos já rastreados desaparecerem. Você deve removê-los explicitamente pelo cliente desktop (Mark for delete + checkin) se quiser tirá-los do repo.