.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

Padrão	Efeito
foo.txt	Qualquer arquivo chamado foo.txt em qualquer nível da árvore
foo/	Todas as pastas chamadas foo e seu conteúdo, em qualquer nível (padrões de pasta sempre correspondem em qualquer profundidade)
foo	Qualquer arquivo OU pasta chamado foo em qualquer nível (sem barra final)

Curingas

Padrão	Efeito
*.tmp	Todos os arquivos .tmp em qualquer nível
*.{tmp,bak,old}	Expansão de chaves: equivale a *.tmp + *.bak + *.old
foo*	Qualquer arquivo ou pasta cujo nome comece com foo
?ile.txt	O ? corresponde a exatamente um caractere: file.txt, pile.txt, etc.
[abc].txt	Classe de caracteres: a.txt, b.txt, c.txt
**/build/	Recursivo: qualquer pasta build/ em qualquer nível (equivalente a build/)
Content/**/Tmp/	Recursivo no meio: qualquer pasta Tmp/ situada em algum lugar sob Content/
Content/**	Tudo sob Content/, em qualquer profundidade

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, distribuída em forma binária), mesmo que uma regra tentasse incluí-lo.
2. Segmento ThirdParty: se um segmento do caminho se chama exatamente ThirdParty, o arquivo nunca é ignorado. Ver Pasta ThirdParty.
3. Prefixo de plugin autorizado de ofício (o Binaries/ de um plugin instalado sem código-fonte): nunca é ignorado.
4. Caso contrário: o caminho é ignorado se corresponder a um dos padrões do arquivo.

Os três primeiros passos são decisões definitivas: assim que um deles se aplica, o próximo não é avaliado, e seus padrões não são consultados de forma alguma. É por isso que não se pode "neutralizar" nenhum deles com uma regra mais precisa.

Template UE5 padrão

Aqui está, linha por linha, o que o cliente desktop escreve no momento do clone em um workspace UE5. Se você copiar este bloco à mão para um projeto existente, copie-o por inteiro: as seções "IDE" e "geração de projeto Linux" são as que mais frequentemente se esquecem, e a ausência delas faz com que arquivos de projeto regenerados a cada build sejam rastreados, o que então acaba em conflito para todo 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

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 cujo segmento se chame ThirdParty é sempre rastreado, seja qual for a regra que o designasse. É uma convenção do Unreal: ThirdParty contém as bibliotecas pré-compiladas (.lib, .dll, .so, .a) de que a compilação do projeto precisa. Excluí-las quebraria o build para todos os seus colegas de equipe.

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

Mesmo que você escreva **/lib/, *.lib ou *.dll no seu .uversionignore, esse arquivo continua rastreado.

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.