Git LFS로 3D 메시와 VFX 파티클 파일 체계적으로 관리하기

왜 게임 에셋은 일반 Git만으로 관리하기 어려운가

FBX, Blender 파일, 텍스처, 파티클 시스템처럼 게임 에셋 대부분은 바이너리 파일이다. 소스 코드와 달리 줄 단위 비교와 병합이 거의 불가능하다. 파일이 조금만 바뀌어도 Git은 새 바이너리 덩어리를 커밋 이력에 계속 쌓는다.

그 결과 저장소 복제와 CI 체크아웃이 느려지고 큰 에셋을 되돌리거나 정리하기도 어려워진다. 같은 프리팹이나 맵을 두 사람이 수정하면 자동 병합 대신 충돌 해결 또는 한쪽 변경의 포기가 필요해질 수 있다.

Git LFS는 Git 커밋에는 작은 포인터 파일만 저장하고 실제 대용량 파일은 LFS 저장소에 따로 보관한다. 다만 LFS는 충돌을 자동으로 해결하는 도구가 아니다. 대용량 파일의 저장 방식을 바꾸는 도구이므로 폴더 구조와 편집 규칙을 함께 정해야 효과가 있다.

Git LFS의 동작 방식

flowchart LR
    A[아티스트가 FBX 수정] --> B[git add]
    B --> C[Git 커밋에는 LFS 포인터 기록]
    B --> D[실제 FBX는 LFS 저장소에 업로드]
    C --> E[다른 개발자가 git pull]
    D --> E
    E --> F[포인터를 실제 에셋으로 내려받음]

.gitattributes에 추적 규칙을 등록하면 해당 확장자는 LFS가 관리한다. 포인터 파일에는 실제 파일의 내용 대신 객체 식별자와 크기 같은 정보가 들어간다. 따라서 일반 Git 이력의 팽창은 줄일 수 있지만 LFS 서버의 저장 공간과 전송량은 별도로 관리해야 한다.

시작하기: 설치와 추적 규칙

각 개발 환경에서 한 번 설치한다.

git lfs install

프로젝트 루트에서 파일 종류별로 LFS 추적 규칙을 추가한다.

git lfs track "*.fbx"
git lfs track "*.blend"
git lfs track "*.uasset"
git lfs track "*.umap"
git lfs track "*.psd"
git lfs track "*.exr"

명령을 실행하면 .gitattributes가 만들어지거나 갱신된다. 이 파일은 팀 전체가 같은 규칙을 적용하도록 반드시 일반 Git으로 커밋한다.

git add .gitattributes
git commit -m "Configure Git LFS asset tracking"

규칙이 적용됐는지 확인할 때는 다음 명령을 쓴다.

git lfs track
git lfs ls-files

이미 일반 Git으로 커밋한 대용량 파일은 추적 규칙을 추가했다고 자동으로 LFS로 옮겨지지 않는다. 이후 새로 추가하거나 변경하는 파일부터 적용된다. 기존 이력까지 옮기는 작업은 커밋 해시를 바꾸므로 팀과 백업 계획을 합의한 뒤 git lfs migrate import를 사용해야 한다.

에셋 종류보다 작업 흐름을 기준으로 폴더를 나눈다

확장자만 보고 모든 바이너리를 LFS로 보내면 필요한 파일과 불필요한 파일을 구분하기 어렵다. 특히 생성물과 원본을 분리해야 한다.

Assets/Art/Source/: Blender 원본, PSD 원본 등 편집 가능한 제작 원본
Assets/Art/Meshes/: 런타임에서 사용하는 FBX 또는 엔진 임포트 결과
Assets/VFX/: 파티클 그래프, 머티리얼, 시뮬레이션 캐시
Assets/Maps/: 레벨과 월드 데이터
Build/, Library/, DerivedDataCache/: 버전 관리하지 않는 생성물과 캐시

Unity에서는 Library/, Temp/, Logs/ 같은 생성 디렉터리를 .gitignore로 제외하는 것이 기본이다. Unreal Engine도 Binaries/, Intermediate/, Saved/, DerivedDataCache/를 보통 제외한다. 이 폴더들은 크더라도 LFS로 보낼 대상이 아니라 로컬 또는 빌드 과정에서 재생성할 대상이다.

Git LFS로 관리하는 원본 에셋과 Git에서 제외하는 생성 캐시를 구분한 게임 프로젝트 폴더 구조

충돌을 줄이는 핵심: 잠금과 소유권

FBX나 .uasset처럼 병합이 사실상 불가능한 파일은 한 사람이 편집하는 동안 다른 사람이 수정하지 않도록 해야 한다. Git LFS 파일 잠금을 사용할 수 있다.

git lfs lock Assets/Art/Meshes/hero.fbx
# 파일 편집과 테스트 후
git add Assets/Art/Meshes/hero.fbx
git commit -m "Update hero mesh"
git push
git lfs unlock Assets/Art/Meshes/hero.fbx

모든 파일을 잠그면 작업이 느려진다. 다음처럼 병합 불가 파일에만 적용하는 편이 낫다.

*.fbx filter=lfs diff=lfs merge=lfs -text lockable
*.blend filter=lfs diff=lfs merge=lfs -text lockable
*.uasset filter=lfs diff=lfs merge=lfs -text lockable
*.umap filter=lfs diff=lfs merge=lfs -text lockable

잠금은 협업 규칙을 보조한다. 더 중요한 것은 파일을 작게 나누고 담당 범위를 분명히 하는 일이다. 예를 들어 하나의 거대한 VFX 라이브러리 파일보다 효과별 파일을 만들고 하나의 월드 파일보다 스트리밍 단위 또는 서브레벨로 나누는 편이 충돌 범위를 줄인다.

Unity와 Unreal에서 확인할 점

Unity

Unity의 텍스트 직렬화가 가능한 에셋은 YAML 형태로 저장되어 일부 변경을 비교할 수 있다. Edit > Project Settings > Editor에서 Asset Serialization을 Force Text로 설정하면 프리팹과 씬의 비교 가능성이 좋아진다. 그러나 머티리얼, 텍스처, FBX처럼 본질적으로 바이너리인 파일까지 병합 가능해지는 것은 아니다.

Unity 메타 파일은 에셋 참조를 유지하는 데 필요하므로 .meta 파일을 반드시 함께 커밋한다. 에셋만 올리고 메타 파일을 빼면 참조가 깨지거나 팀원의 임포트 결과가 달라질 수 있다.

Unreal Engine

Unreal의 .uasset, .umap은 일반적으로 바이너리이며 Git LFS 대상에 적합하다. 월드와 블루프린트 에셋의 충돌을 줄이려면 작업 단위를 나누고 수정 전 잠금 여부를 확인한다.

대규모 프로젝트에서는 Git LFS만으로 모든 문제를 해결하려 하기보다 Unreal의 협업 기능, 분할된 월드 구성, 에셋 소유권 규칙을 함께 검토한다. 특히 엔진이 생성하는 중간 파일과 캐시는 저장소에 넣지 않는다.

운영 체크리스트

LFS 추적 규칙과 .gitignore를 프로젝트 시작 시점에 합의한다.
원본 에셋과 엔진 생성물을 분리한다.
병합 불가 파일만 잠금 대상으로 지정한다.
커밋 전에 git lfs ls-files로 큰 파일이 LFS에 들어갔는지 확인한다.
원격 저장소의 LFS 저장 용량과 월간 전송량 제한을 확인한다.
기존 이력 마이그레이션은 백업과 팀 공지 후에만 진행한다.

마무리

Git LFS는 대용량 게임 에셋을 Git 저장소에서 분리해 복제와 이력 관리를 안정시키는 기반이다. 하지만 충돌을 없애지는 않는다. 에셋을 작업 단위로 나누고 생성 파일을 제외하며 병합 불가 파일에는 잠금과 담당 규칙을 적용해야 3D 메시와 VFX 파일을 지속적으로 관리할 수 있다.