[TIL_250217] Git LFS와 언리얼 엔진

💭회고

오늘은 프로젝트 세팅 과정을 진행하면서...
언리얼 엔진 프로젝트에서 Git LFS(Large File Storage)를 사용하여 대용량 파일을 효율적으로 관리하는 방법에 대해 다시 한번 알아봤다. 이 글에서 Git LFS의 필요성, 기본 개념, 설치 및 설정 방법, 활용법, 그리고 주의사항까지 적어보았다.

🗺️마인드맵

📒학습 내용

1. 왜 언리얼 프로젝트에 Git LFS가 필요할까?

언리얼 엔진 프로젝트는 텍스처, 사운드 파일, 모델 파일 등 대용량 데이터가 많아 일반적인 Git으로는 관리가 어렵다.

• 언리얼 프로젝트의 특징: 텍스처, 사운드, 모델 파일 등 대용량 데이터 多
• 일반 Git의 파일 크기 제한: GitHub 무료 라이선스 기준으로 50MB 초과 시 경고, 100MB 초과 시 업로드 차단...
• Git LFS의 필요성: 100MB 이상의 대용량 파일 관리 시 필수

GitHub에서 기본 플랜 기준으로 100MB가 넘는 파일은 업로드가 차단되므로, Git LFS는 필수적인 선택이다.

그렇다면 Git LFS가 뭘까?

 

---

2. Git LFS란 무엇이고, 어떻게 동작할까?

Git LFS(Large File Storage)는 Git 저장소가 대용량 파일을 효율적으로 관리할 수 있도록 돕는 오픈 소스 Git 확장 기능이다.

동작 원리:

1. 실제 파일 대신 파일의 포인터(경로, 메타데이터)를 Git 저장소에 저장
2. 포인터는 .gitattributes 파일에 정의된 규칙에 따라 생성💫
3. 대용량 파일은 LFS 서버에 업로드 후 필요 시 다운로드
4. 개발자가 파일을 커밋하면 Git은 LFS 설정 파일 유형을 인식하고, 파일 내용을 LFS 서버로 전송한 뒤 Git 저장소에는 해당 파일의 참조 정보만 기록

LFS 서버: GitHub, GitLab 등 원격 저장소 제공자가 기본 제공, 또는 별도 구축도 가능하다.

---

3. Git LFS, 이렇게 설치하자

1. Git LFS 설치: 공식 사이트에서 설치 파일을 다운로드
https://git-lfs.com/

Git Large File Storage

2. Git LFS 활성화: 설치 후 깃과 Clone해둔 경로에서 Open Git Bash

3. 명령어 git lfs install을 실행한다.

git lfs install

// 아래 로그가 나오면 정상적으로 초기화된 것
> Updated Git hooks.
> Git LFS initialized.

4. 언리얼 프로젝트에 Git LFS 적용

1) .gitignore 설정: 언리얼 엔진에서 제공하는 기본 .gitignore 파일에 예외를 설정한다.

# Visual Studio 2015 user specific files
.vs/

# Jetbrain Rider specific files
.idea/

# Compiled Object files
*.slo
*.lo
*.o
*.obj

# Precompiled Headers
*.gch
*.pch

# Compiled Dynamic libraries
*.so
*.dylib
*.dll

# Fortran module files
*.mod

# Compiled Static libraries
*.lai
*.la
*.a
*.lib

# Executables
*.exe
*.out
*.app
*.ipa

# These project files can be generated by the engine
*.xcodeproj
*.xcworkspace
*.sln
*.suo
*.opensdf
*.sdf
*.VC.db
*.VC.opendb

# Precompiled Assets
SourceArt/**/*.png
SourceArt/**/*.tga

# Binary Files
Binaries/*
Plugins/**/Binaries/*

# Builds
Build/*

# Whitelist PakBlacklist-<BuildConfiguration>.txt files
!Build/*/
Build/*/**
!Build/*/PakBlacklist*.txt

# Don't ignore icon files in Build
!Build/**/*.ico

# Built data for maps
*_BuiltData.uasset

# Configuration files generated by the Editor
Saved/*

# Compiled source files for the engine to use
Intermediate/*
Plugins/**/Intermediate/*

# Cache files for the editor to use
DerivedDataCache/*

2) .gitattributes 파일 설정: LFS 파일로 관리할 파일 형식 지정한다.

// 예시
git lfs track "*.uasset" ! 언리얼 내 에셋 파일 확장자
git lfs track "*.umap"   ! 언리얼 내 레벨 파일 확장자
git lfs track "*.png"    ! 이미지 파일 확장자
git lfs track "*.wav"    ! 음원 파일 확장자
git lfs track "*.bk2"    ! 언리얼 엔진 내 영상 작업물 확장자

[attr]lock filter=lfs diff=lfs merge=binary -text lockable
[attr]lockonly lockable
[attr]lfs filter=lfs diff=lfs merge=binary -text
[attr]lfstext filter=lfs diff=lfstext merge=lfstext -text
# Unreal Engine file types.
*.uasset lock
*.umap lock
*.locres lfs
*.locmeta lfs
# Steam Audio files
*.phononscene lfs
*.probebox lfs
*.probebatch lfs
*.bakedsources lfs
# Binaries
*.exe lfs
*.dll lfs
*.rcc lfs
# FMOD
*.bank lfs
*.wav lfs
*.mp3 lfs
*.ogg lfs
*.flac lfs
# Icons
*.png lfs
*.ico lfs
*.icns lfs
# Movies
*.bk2 lfs

3) 파일 추가 및 커밋 : 아래와 같이 명령어를 넣는 방법도 있지만, 초보자는 GitDesktop을 쓰는 편이 편하다.

git add .gitattributes
git commit -m "Initialize Unreal Project with LFS"

4) 원격 저장소에 업로드 :

git push origin main

---

4. 언리얼 엔진에서 Git LFS, 이렇게 활용해보자

🔒파일 잠금 (File Locking)

• 목적: 여러 팀원이 같은 파일을 수정할 때 충돌 방지
• 기능: 특정 파일 수정 시 해당 파일을 잠가 다른 사람의 접근을 막는다.
• 효과: 충돌 해결에 소요되는 시간 절약

💠외부 플러그인 활용

1. 플러그인 설치: GitHub Release에서 UEGitPlugin 다운로드 후 프로젝트 경로/Plugins 폴더에 붙여 넣는다. Plugins 폴더가 없다면 새로 생성한다.
2. Config 세팅: 프로젝트 경로에서 Config 폴더 안에 DefaultEditorPerProjectUserSettings.ini 파일을 생성한 뒤 내용에 아래 텍스트를 붙여넣고 저장한다.

[/Script/UnrealEd.EditorLoadingSavingSettings]
bSCCAutoAddNewFiles=False
bAutomaticallyCheckoutOnAssetModification=True
bPromptForCheckoutOnAssetModification=False

💠언리얼 리비전 컨트롤 세팅

리비전 컨트롤?? : 언리얼에서 사용할 형상관리 프로그램을 관리하는 기능

1. 리비전 컨트롤 설정: '메뉴 바/Tools/Connect to Revision Control' 선택 후 Git LFS 2를 선택한다.

2. GitHub 프로필 설정: Uses Git LFS 설정에 GitHub 프로필 명을 기재한다.

🚨Uses Git LFS 칸에 깃 계정 아이디랑 반드시 같게 입력 해야한다. 해당 깃을 못쓰게 될 수도 있다... 풀 수 있더라도 번거롭게 된다. 오타를 방지하기 위해 복사해서 붙여넣자.

💠 파일 잠금 실습
1. 파일 잠금: 수정할 폴더나 에셋을 콘텐츠 브라우저에서 우클릭하여 Check Out을 선택한다. 수정 권한이 있는 사람은 초록색 체크 표시, 없는 사람은 붉은색 자물쇠 표시가 나타난다.

2. 잠금 해제: 잠긴 파일을 콘텐츠 브라우저에서 우클릭 후 '리비전 컨트롤/리버트'를 선택하고 'Revert Unchanged Only'를 체크한다. 

'Revert Unchanged Only’ 를 꼭 체크한 후 수행해야 여러 파일을 되돌릴 때 안전하다

---

5. 언리얼 기능 제한하기

UE 5부터는 포트나이트의 월드를 쾌적하게 만들기 위해 World Partition이라는 스트리밍 기능이 기본적으로 활성화되어 있다.

World Partition ?? ➡️ 대규모 월드를 효율적으로 관리하기 위한 기능이다. 월드에 있는 모든 액터를 하나의 파일로 만들어 관리하는 Actor Per File 기능을 필수로 활성화 하게 한다.(맵 파일을 더 작은 액터 파일로 분할하여 여러 사람이 동시에 작업할 수 있게 한다.) 이는 에셋 포인터가 추가되면 지울 수 없는 LFS 환경에 부담을 줄 수 있다. 

 

그래서 비활성화 해야 한다.

💠비활성화 방법:

1. 프로젝트 세팅: 프로젝트 세팅 내 월드 파티션에서 'New Maps Enable World Partition' 옵션을 비활성화한다.

2. 월드 세팅 수정: 이미 생성된 레벨에서는 해당 레벨에 들어가 월드 세팅에서 'Enable Streaming'을 비활성화하고, 'Disable World Partition' 버튼을 클릭한 후, 'Use External Actors'를 비활성화한다.

Enable Streaming을 비활성화

Disable World Partition에 Disable 버튼을 클릭

Use External Actors를 비활성화

---

6. 에셋 이주

사용하는 에셋과 플러그인을 다운 받고, 본 프로젝트에 내용물을 가져올 때 사용한다.
이러한 이주 기능을 이용하여 모든 컨텐츠를 가져오지 않고 필요한 컨텐츠만 가져오도록 한다.

---

7. 프로젝트 관리 시 주의사항

Git LFS를 사용할 때는 커밋 메시지를 명확하고 간결하 작성하고, 불필요한 대용량 파일은 제거하여 저장소 용량을 효율적으로 관리해야 한다!

🔗 참고 자료

https://joong-sunny.github.io/programming/git-file-size/

github에 용량큰 파일 올리기

---

🐞트러블슈팅

01. GitLFS에다가 프로젝트를 올리려고 보니... 프젝 용량이 23.1GB정도 하였다.

02. 왜냐? 이미 맵 에셋을 활용한 기초 레벨 디자인을 초안을 잡았고, 이전에 작업해둔 드론 에셋을 담아두었기 때문이다.

03. 드론은 용량이 얼마하지 않고, 맵이 용량의 대부분을 차지했다.

04. 맵의 메시도 상당했지만 사실상 제일 많이 차지하는 것은 텍스처!

05. 제한된 LFS 용량은 20GB 🛑

06. 첫 번째 시도는 임시 파일 (.vs 등 캐시 및 설정파일)을 삭제하고 올렸으나 .gitignore를 설정했으니 그럴 필요가 없었다...!

07. 콘텐츠에 있는 에셋들을 좀 정리하고 보니, 10GB까지 줄여서 문제가 없겠다고 판단하고 다시 깃에다가 커밋을 시도! 🟢

08. (에셋에서 레퍼런스 되지 않는 메시나 텍스처는 감지해서 삭제를 편하게 해주는 플러그인이나 방법은 없으려나🤔)

09. 커밋 시도했으나 아래와 같은 오류가 발생 🛑

10. 프로젝트를 옮길 때, 깃이 연동된 경로에 폴더 채로 옮기는 바람에 꼬인듯 하다.

11. 내부에 있는 자료들을 꺼내주고 커밋 시도... 콘텐츠 용량만 10GB 라서 1시간 정도 걸린듯하다. 결론적으로 커밋은 정상 🟢

12. Push까지도 마무리해서 완료! (Push 역시 1시간 가량 걸린듯)

09. 커밋 시도했으나 아래와 같은 오류가 발생  🛑

---

🟣오늘의 옵시디언 현황