Git LFS로 대용량 VFX·3D 메시 프로젝트 용량 관리한 개발 로그
Git LFS로 Unity·Unreal 프로젝트의 VFX 텍스처와 3D 메시를 분리 관리한 기록입니다. 추적 패턴, 마이그레이션, 저장소 용량 점검, 협업 시 주의점을 실제 적용 순서로 정리했습니다.
핵심 요약
Git LFS(Git Large File Storage)는 대용량 바이너리 파일의 실제 데이터를 별도 LFS 저장소에 두고 Git 커밋에는 작은 포인터 파일만 남기는 방식이다. 이번 프로젝트에서는 VFX 텍스처, FBX 메시, 고해상도 소스 파일을 Git LFS로 추적해 일반 Git 히스토리 비대화를 막고 클론·풀 작업의 예측 가능성을 높였다.
핵심은 git lfs track으로 바이너리 확장자만 선별하고 이미 Git 히스토리에 들어간 대용량 파일은 필요할 때만 git lfs migrate import로 이관하는 것이다.
왜 VFX와 3D 메시가 Git 저장소를 빠르게 키우는가?
게임 프로젝트의 VFX와 3D 에셋은 사람이 읽을 수 없는 바이너리 파일이 많고 수정할 때마다 파일 전체가 새 버전으로 저장되는 경향이 있다. 특히 텍스처 해상도 변경, 메시 재익스포트, Niagara·Unity VFX Graph용 소스 교체는 파일 크기 대비 변경 횟수가 빠르게 누적된다.
일반 Git은 텍스트 차이 계산에 강하지만 FBX·PSD·TGA·EXR처럼 압축되었거나 구조가 크게 바뀌는 바이너리 파일에서는 델타 압축 효율이 제한적이다. 같은 파일 경로의 에셋을 여러 번 교체하면 현재 작업 트리는 작아 보여도 .git 히스토리는 계속 커질 수 있다.
| 파일 유형 | 일반 Git에서 생기는 문제 | Git LFS 적용 판단 |
|---|---|---|
.fbx, .blend | 재익스포트마다 큰 바이너리 버전이 누적됨 | 권장 |
.psd, .tga, .exr | 원본·고해상도 텍스처의 용량이 큼 | 권장 |
.uasset, .umap | Unreal 바이너리 에셋, 병합이 어려움 | 팀 정책에 따라 권장 |
.prefab, .mat, .shader | 텍스트 기반이거나 비교 가능한 경우가 많음 | 일반 Git 유지 |
| 빌드 결과물 | 재생성 가능하고 변경량이 큼 | Git·LFS 모두 제외 |
Git LFS는 대용량 게임 에셋을 어떻게 관리할까?
Git LFS는 Git 객체에 대용량 파일 전체를 넣지 않는다. 대신 파일의 SHA-256 식별자와 크기가 담긴 포인터 파일을 커밋하고 실제 바이너리 데이터는 LFS 서버에 업로드한다.
대표적인 포인터 파일은 다음과 같은 형태다.
version https://git-lfs.github.com/spec/v1
oid sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
size 52428800이 구조 덕분에 일반 Git 객체 데이터베이스가 대용량 에셋 이력으로 팽창하는 문제를 줄일 수 있다. 단, LFS 서버의 저장 공간과 전송량은 별도로 관리해야 한다. Git LFS는 용량을 없애는 도구가 아니라 대용량 파일의 저장 위치와 전송 방식을 분리하는 도구다.
프로젝트에 Git LFS를 어떻게 적용했는가?
1. 팀 도구에 Git LFS를 설치하고 초기화한다
모든 작업자가 Git LFS를 설치한 뒤 각 로컬 환경에서 한 번 초기화한다.
git lfs install
git lfs versiongit lfs install은 Git 훅을 설정해 LFS 추적 파일이 커밋·푸시될 때 LFS 저장소로 전송되도록 한다. CI 환경에서 에셋이 필요한 빌드를 수행한다면 CI 이미지에도 Git LFS가 설치되어 있어야 한다.
2. VFX·3D 메시 확장자만 추적한다
프로젝트 루트에서 필요한 확장자만 명시적으로 등록했다. 지나치게 넓은 패턴으로 모든 파일을 LFS에 넣으면 텍스트 파일의 diff와 코드 리뷰 장점을 잃을 수 있다.
git lfs track "*.fbx"
git lfs track "*.blend"
git lfs track "*.psd"
git lfs track "*.tga"
git lfs track "*.exr"
git add .gitattributes
git commit -m "chore: track large art assets with git lfs"명령은 .gitattributes에 다음과 같은 규칙을 기록한다.
*.fbx filter=lfs diff=lfs merge=lfs -text
*.blend filter=lfs diff=lfs merge=lfs -text
*.psd filter=lfs diff=lfs merge=lfs -text
*.tga filter=lfs diff=lfs merge=lfs -text
*.exr filter=lfs diff=lfs merge=lfs -text.gitattributes는 반드시 일반 Git으로 커밋한다. 이 파일이 팀의 에셋 추적 정책 자체이기 때문이다.
3. 새 에셋을 추가하고 LFS 추적 여부를 확인한다
새 FBX 또는 텍스처를 추가한 뒤에는 커밋 전 실제 추적 상태를 확인했다.
git add Assets/VFX/Fire/Textures/fire_mask.exr
git lfs status
git lfs ls-files
git commit -m "art: add fire vfx source texture"git lfs status에 해당 파일이 표시되고 git lfs ls-files에서 추적 목록을 확인할 수 있으면 정상이다. 파일을 먼저 일반 Git으로 커밋한 뒤 LFS 규칙을 추가하면 과거 커밋의 대용량 객체는 그대로 남는다.
이미 커밋한 대용량 파일은 어떻게 이관할까?
기존 히스토리에 대용량 FBX나 PSD가 이미 들어갔다면 git lfs migrate import를 검토한다. 이 명령은 커밋 해시를 다시 쓰므로 공유 브랜치에서는 팀 합의와 백업 없이 실행하면 안 된다.
git lfs migrate import --include="*.fbx,*.psd,*.tga,*.exr" --everything
git push --force --all
git push --force --tags마이그레이션은 저장소를 근본적으로 정리할 수 있지만 모든 개발자가 새 히스토리를 받아야 한다는 비용이 있다. 이번 운영에서는 다음 기준으로 결정하는 편이 안전했다.
| 상황 | 선택 |
|---|---|
| 대용량 파일이 최근 한두 개이고 저장소 문제가 아직 작음 | LFS 규칙만 추가하고 이후 파일부터 적용 |
| 과거 대용량 에셋 때문에 클론·CI가 이미 느림 | 점검 후 히스토리 마이그레이션 |
| 외부 협업자와 장기 브랜치가 많음 | 릴리스 직후처럼 전환 가능한 시점에 진행 |
Git LFS 적용 후 무엇을 점검해야 하는가?
LFS 적용만으로 협업 문제가 끝나지는 않는다. 에셋을 내려받지 못한 상태에서 엔진을 열면 포인터 파일 때문에 임포트 오류나 누락 에셋처럼 보일 수 있다.
클론과 CI에서 LFS 파일을 받는지 확인한다
일반적인 클론에서는 LFS 파일도 함께 내려받지만 환경이나 캐시 설정에 따라 명시적으로 처리하는 편이 안전하다.
git lfs pull에셋이 필요 없는 분석·문서 CI라면 LFS 다운로드를 생략할 수 있다. 반대로 Unity 또는 Unreal 빌드 CI는 빌드 전에 git lfs pull 또는 동등한 체크아웃 설정을 적용해야 한다.
잠금이 필요한 바이너리 에셋을 구분한다
FBX, PSD, Unreal .uasset처럼 줄 단위 병합이 사실상 불가능한 파일은 동시에 수정하면 마지막 반영본이 다른 작업을 덮어쓸 수 있다. Git LFS 잠금을 지원하는 원격 저장소라면 아트 원본처럼 충돌 비용이 큰 파일에만 잠금을 사용한다.
git lfs lock Assets/Characters/Hero/hero_body.fbx
git lfs unlock Assets/Characters/Hero/hero_body.fbx모든 파일을 잠그는 방식은 작업 흐름을 막기 쉽다. 재생성이 어려운 원본 파일과 동시에 수정될 가능성이 높은 파일만 대상으로 삼는 것이 현실적이다.
용량과 전송량을 분리해서 본다
git count-objects -vH는 로컬 Git 객체 크기를 확인하는 데 유용하고 git lfs ls-files --size는 현재 체크아웃 기준 LFS 파일 크기를 살펴볼 때 쓸 수 있다.
git count-objects -vH
git lfs ls-files --size원격 호스팅 서비스의 LFS 저장 공간과 대역폭 한도도 함께 확인해야 한다. 대형 텍스처를 자주 교체하는 프로젝트에서는 Git 저장소보다 LFS 전송량이 먼저 운영 비용의 기준이 될 수 있다.
자주 묻는 질문 (FAQ)
Git LFS를 쓰면 Git 저장소 용량이 완전히 줄어드는가?
아니다. 새 LFS 파일의 실제 데이터가 Git 객체 히스토리에 쌓이는 문제는 줄지만 LFS 서버에는 파일 버전이 저장된다. Git 용량과 LFS 저장·전송량을 따로 관리해야 한다.
Unity의 Library 폴더나 Unreal의 DerivedDataCache도 Git LFS에 넣어야 하는가?
아니다. 둘 다 일반적으로 재생성 가능한 캐시이므로 .gitignore로 제외하는 편이 맞다. Git LFS는 공유해야 하지만 큰 원본 에셋에 사용한다.
모든 .uasset 파일을 Git LFS로 추적해야 하는가?
프로젝트 규모와 협업 방식에 따라 다르다. Unreal 에셋은 바이너리라 LFS가 유용할 수 있지만 먼저 저장소 크기와 충돌 빈도를 측정하고 팀 전체에 일관된 정책을 적용하는 것이 좋다.
정리: LFS는 에셋 정책과 함께 운영해야 한다
이번 정리에서 가장 효과적이었던 선택은 모든 파일을 LFS로 옮기는 것이 아니라 재생성 불가능하고 변경당 용량이 큰 VFX·3D 원본만 선별한 일이었다. .gitattributes로 추적 규칙을 버전 관리하고 CI의 LFS 다운로드 여부와 바이너리 파일 잠금 규칙까지 같이 점검해야 실제 프로젝트에서 안정적으로 작동한다.
다음 마일스톤에서는 에셋 폴더별 LFS 용량을 정기적으로 기록하고 불필요한 고해상도 소스나 중복 익스포트 파일을 제작 파이프라인 단계에서 줄일 계획이다.
