.uversionignore

소개

워크스페이스 루트에 있는 .uversionignore 파일은 클라이언트가 트래킹, 업로드하거나 커밋에 포함해서는 안 되는 파일과 폴더를 정의합니다. .gitignore 스타일 구문(하위 집합: 주석, /로 끝나는 폴더 패턴, 이름/확장자 glob)이며, globset으로 컴파일됩니다. 이것은 완전한 gitignore가 아닙니다. !를 통한 부정과 앵커링은 지원되지 않습니다. 몇 가지 Unreal Engine 특정 규칙은 아래에 설명되어 있습니다.

이 파일은 clone 시 데스크톱 클라이언트에 의해 기본 UE5 템플릿으로 자동 생성됩니다. 이후 프로젝트에 맞게 편집할 수 있습니다.

이 파일 자체도 트래킹됩니다. 편집하고 커밋하면 협업자는 다음 sync에서 변경 사항을 가져옵니다. 이것은 의도적인 동작입니다. 스튜디오 전체가 동일한 제외 규칙을 공유합니다.

구문

한 줄에 하나의 규칙. 빈 줄과 #로 시작하는 줄은 무시됩니다(주석).

기본 패턴

패턴	효과
foo.txt	트리의 어느 레벨에 있든 foo.txt라는 이름의 모든 파일
foo/	foo라는 이름의 모든 폴더와 그 내용, 어느 레벨에서든(폴더 패턴은 항상 모든 깊이에서 일치합니다)
foo	어느 레벨에 있든 foo라는 이름의 파일 또는 폴더(끝 슬래시 없음)

와일드카드

패턴	효과
*.tmp	어느 레벨에 있든 모든 .tmp 파일
*.{tmp,bak,old}	중괄호 확장: *.tmp + *.bak + *.old와 동일
foo*	이름이 foo로 시작하는 모든 파일 또는 폴더
?ile.txt	?는 정확히 한 문자와 일치합니다: file.txt, pile.txt 등
[abc].txt	문자 클래스: a.txt, b.txt, c.txt
**/build/	재귀적: 어느 레벨에 있든 모든 build/ 폴더(build/와 동일)
Content/**/Tmp/	중간 재귀: Content/ 아래 어딘가에 있는 모든 Tmp/ 폴더
Content/**	Content/ 아래의 모든 것, 어느 깊이에서든

부정 없음(!)

.gitignore와 달리 uVersion은 파일을 다시 포함하기 위한 ! 접두사를 지원하지 않습니다. !로 시작하는 줄은 예외가 아니라 리터럴 패턴으로 처리됩니다. 무시된 폴더 내 파일의 재트래킹은 자동 규칙을 통해서만 이루어집니다. ThirdParty 예외 처리와 설치된 플러그인의 Binaries/ 화이트리스트입니다(아래 참조).

주석

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

줄 중간에 있는 #는 주석이 아닙니다. 패턴의 일부입니다. 줄 시작 부분(선택적 공백 뒤)에 있는 #만 주석을 시작합니다.

규칙 우선순위

파일 내 줄의 순서는 중요하지 않습니다. 모든 패턴은 단일 GlobSet으로 컴파일되며, 경로는 그중 하나에 일치하는 즉시 무시됩니다. 결정은 다음 순서로 고정된 우선순위를 따릅니다:

1. 예약된 경로 Plugins/uVersion: 항상 무시됩니다(도구가 관리하는 폴더, 바이너리 형태로 배포). 규칙이 포함하려고 해도 마찬가지입니다.
2. ThirdParty 세그먼트: 경로 세그먼트의 이름이 정확히 ThirdParty인 경우 파일은 절대 무시되지 않습니다. ThirdParty 폴더 참조.
3. 기본적으로 허용되는 플러그인 접두사(소스 코드가 없는 설치된 플러그인의 Binaries/): 절대 무시되지 않습니다.
4. 그 외: 경로는 파일의 패턴 중 하나에 일치하면 무시됩니다.

처음 세 단계는 확정적인 결정입니다: 그중 하나가 적용되는 즉시 다음 단계는 평가되지 않으며, 여러분의 패턴은 전혀 참조되지 않습니다. 그렇기 때문에 더 정밀한 규칙으로 그중 하나를 "무력화"할 수 없습니다.

기본 UE5 템플릿

다음은 UE5 워크스페이스에서 clone 시 데스크톱 클라이언트가 기록하는 내용을 한 줄도 빠짐없이 보여준 것입니다. 이 블록을 기존 프로젝트에 직접 복사한다면 전체를 그대로 복사하세요: "IDE"와 "Linux 프로젝트 생성" 섹션이 가장 자주 잊히는 부분이며, 이것들이 빠지면 빌드할 때마다 재생성되는 프로젝트 파일이 추적 대상이 되어 결국 모두에게서 충돌이 발생합니다.

# 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

이 파일에 자신만의 규칙을 추가할 수 있습니다. 스튜디오 전체가 동일한 제외를 갖도록 잊지 말고 커밋하세요.

플러그인

예약된 폴더 Plugins/uVersion

Plugins/uVersion 폴더(uVersion 플러그인 자체)는 어느 깊이에서든 항상 무시되며, 이 규칙은 다른 모든 것보다 우선합니다. 데스크톱 클라이언트가 관리하며(바이너리 배포) 절대 커밋해서는 안 됩니다. Plugins/uVersionExtras와 같은 인접 폴더는 영향을 받지 않습니다.

uVersion은 파일에 아무것도 작성하지 않고도 다른 플러그인에 대한 스마트 로직도 적용합니다:

• 플러그인이 .uplugin에 "Installed": true를 가지고 있고 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

.uversionignore에 **/lib/, *.lib 또는 *.dll을 작성하더라도 이 파일은 계속 추적됩니다.

일반적인 레시피

외부 아트 소스가 있는 프로젝트(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é

또는 더 직접적으로 jq 필터를 사용한 JSON 모드로:

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

일반적인 함정

끝 슬래시 = 폴더, 슬래시 없음 = 모호함

foo는 파일 foo와 폴더 foo/를 모두 무시합니다. foo/는 폴더만 무시합니다. 정확하게 하려면 폴더에는 끝 슬래시를 붙이세요.

대소문자 구분

패턴은 대소문자를 구분합니다. Content/는 content/와 일치하지 않습니다. Windows는 FS 측에서 대소문자를 구분하지 않으므로, Windows의 한 개발자가 Content/로 이름 짓고 다른 개발자가 content/로 이름 지으면 조용한 충돌이 발생할 수 있습니다. Content/로 표준화하세요.

재포함 불가(!)

!Saved/Config/Foo.ini를 작성해도 아무것도 다시 포함되지 않습니다. 부정은 지원되지 않으며 이 줄은 리터럴 패턴으로 처리됩니다. 하위 폴더를 유지하려면 Saved/ 전체가 아니라 제외하려는 하위 트리만(예: Saved/Logs/, Saved/Backup/) 무시하세요.

너무 광범위한 패턴

*.zip은 워크스페이스의 모든 .zip을 무시합니다. 의도적으로 .zip으로 이름 지은 게임 에셋(드물지만 어드벤처 게임 / 데이터 파일에서 발생)도 포함됩니다. 더 구체적인 패턴을 권장합니다: dist/*.zip, Releases/*.zip 등.

.uversionignore 편집은 이미 커밋된 파일에 영향을 주지 않음

git처럼 .uversionignore에 패턴을 추가해도 이미 트래킹된 파일은 사라지지 않습니다. 리포지토리에서 제거하려면 데스크톱 클라이언트(Mark for delete + checkin)를 통해 명시적으로 삭제해야 합니다.