Git(깃) LFS(Large File Storage) | Unreal Engine(언리얼 엔진)의 프로젝트들 Git LFS 로 관리 하기 (다른 큰 프로젝트들도 해당됨 like Unity)

Git LFS(Large File Storage)

Git LFS(Large File Storage)는 오디오, 비디오, 데이터셋, 그래픽 디자인 파일 등 용량이 큰 대형 파일을 Git에서 효율적으로 관리하기 위한 오픈소스 확장 기능입니다.

사용하는 이유는

저장소 용량 최적화: Git은 파일의 변경 이력을 모두 저장하므로, 대형 파일이 수정될 때마다 저장소 크기가 기하급수적으로 늘어납니다. Git LFS는 이를 방지합니다.
속도 향상: 대형 파일 본문 대신 가벼운 텍스트 포인터(Pointer)만 Git 저장소에 기록하므로, git clone이나 git checkout 속도가 획기적으로 빨라집니다.
원격 스토리지 활용: 실제 대형 파일은 GitHub나 GitLab 등에서 제공하는 별도의 전용 원격 스토리지에 안전하게 보관됩니다.

기본적으로 50MB를 초과하는 파일을 커밋 혹은 푸시하면 경고메세지가 표시되며ㅡ 100MB를 초과하는 파일은 커밋 혹은 , 푸시가 차단되서 불가능 합니다. 또한 GitHub Free 플랜의 Git LFS는 매달 Storage 10GiB, Bandwidth 10GiB 만 주어지며. 해당 용량을 모두 소진하면 더이상 쓸 수 없어지게 됩니다.

https://docs.github.com/ko/billing/concepts/product-billing/git-lfs#included-bandwidth-and-storage-per-month

Git 대형 파일 스토리지 청구 - GitHub 문서

Git 대용량 파일 스토리지의 사용량이 무료 할당량 대비 측정되는 방법 및 추가 사용분에 대한 결제 방법을 알아보세요.

docs.github.com

핵심 작동 방식

[로컬 Git 저장소]              [Git 원격 서버 (GitHub 등)]
  ├── 코드 파일      ───────>    ├── 코드 파일 (실제 저장)
  └── 대형 파일(포인터) ───────>    └── 대형 파일(포인터)
         │                                │
      (자동 전환)                      (자동 전환)
         ▼                                ▼
[실제 대형 파일]     ───────>    [LFS 전용 스토리지]

커밋 시점: 사용자가 대형 파일을 커밋하면, Git LFS가 파일 본문 대신 고유 해시값과 파일 크기가 적힌 몇 줄짜리 텍스트 포인터 파일을 생성하여 Git에 넣습니다.
푸시 시점 (git push): 실제 대형 파일 본문은 Git 서버가 아닌 LFS 전용 대용량 스토리지로 따로 전송됩니다.
클론 시점 (git clone): 원격 저장소를 내려받을 때는 먼저 가벼운 포인터 파일만 다운로드한 뒤, 현재 체크아웃한 버전에 필요한 대형 파일만 LFS 스토리지에서 자동으로 가져옵니다.

간단한 사용 방법 (3단계)

1. 컴퓨터에 LFS 설치 및 초기화

bash

# 최초 1회만 실행 (윈도우는 Git Bash 등에서 실행)
git lfs install

2. 추적할 대형 파일 지정

bash

# 확장자가 .psd인 모든 파일을 LFS로 관리하도록 설정
git lfs track "*.psd"

# 설정 후 생성된 .gitattributes 파일도 함께 Git에 커밋해야 합니다.
git add .gitattributes

3. 평소대로 Git 사용

bash

git add design.psd
git commit -m "Add large design file"
git push origin main

Git LFS로 언리얼 프로젝트 관리하기

효율적인 관리 방법

대용량 애셋을 자주 그리고 많이 푸시할 경우 할당받은 LFS 스토리지 10GiB를 금방 다 쓰게됩니다. 그래서 클론을 자주 시도할 시에는 GitHub Free 플랜에 할당된 LFS 대역폭 10GiB 또한 모두 소진하게됩니다. 만약 대역폭/스토리지를 모두 소진하면 Git 자체가 완전히 막힌다기보다, Git LFS 파일의 다운로드/업로드가 제한됩니다(다음달까지). 이 경우 clone/pull을 해도 실제 대용량 파일 대신 LFS pointer만 받아오거나, LFS 파일 push가 막힐 수 있습니다. 따라서 GitHub Free 플랜 사용시에 효율적인 사용이 필요합니다 (Free 플랜이 아니여도 효율적으로 사용하면 좋겠죠)

1. .gitignore 파일을 통해 필요 없는 폴더/파일 무시.

2. Git Large File Storage를 이용한 대용량 파일 우회 관리.

3. clone 대신 개인 무료 클라우드 + fetch/pull 적극 활용

.gitignore 파일을 통해 필요 없는 폴더/파일 무시

.gitignore 란 리모트(서버)에 올리고 싶은 파일이 있는 반면에, 공유하지 않을 개인 설정·로컬 파일은 빼고 올릴때 해당 파일을 “무시해줘”라는 의미로 .gitignore 파일에 해당 파일의 이름 혹은 폴더 이름을 “미리” 작성해두는 용도로 사용합니다.

깃 리포지토리 생성시 gitignore를 생성하고 그때 설정을 해도되고 따로도 생성가능합니다.

임으로 gitignore 생성,적용 방법: text 파일을 만들고 안에 작성후 파일명을 “.gitignore”로 변경하면 됩니다.

.gitignore 파일 관련 주의사항

1. .gitignore 파일을 만들 때 파일 확장명을 반드시 확인해야 합니다. ex) “.gitignore.txt”로 만드는 실수 빈번하게 발생.

2. .uproject 파일과 같은 폴더에 .gitignore 파일이 있도록 해야합니다.

3. .gitignore는 아직 Git이 추적하지 않는 파일에만 적용됩니다. 이미 커밋된(추적 중인) 파일은 .gitignore에 추가해도 계속 추적됩니다. 이때는 git rm --cached <파일>로 추적만 해제해야 합니다. (로컬 파일 자체는 안 지워집니다.)

4. 리모트에 .gitignore 파일 수정 커밋이 푸시되어 있고, 로컬에서 무시 파일을 올리려하면 푸시 차단됩니다.

Git LFS(Large File Storage)를 사용해서 대용량 파일 우회 관리하는 방법

https://git-lfs.com/

Git Large File Storage

Git Large File Storage (LFS) replaces large files such as audio samples, videos, datasets, and graphics with text pointers inside Git, while storing the file contents on a remote server like GitHub.com or GitHub Enterprise.

git-lfs.com

.gitattributes

.gitattributes는 Git 저장소 내의 특정 파일이나 디렉토리에 대해 개별적인 속성(Attribute)을 부여하여 Git의 동작을 제어하는 설정 파일입니다. 팀원 간 다른 운영체제(Windows, Mac, Linux)를 사용하면서 발생하는 문제를 방지하고, 파일 특성에 맞는 최적의 Git 환경을 구축할 때 주로 사용합니다.

.gitattributes 파일에 명시된 파일들이 LFS 대상 파일로 지정됩니다. LFS 대상 파일의 실제 파일은 LFS 서버에 업로드되고, Git 저장소에는 실제 파일이 아닌 파일의 포인터(경로 및 메타데이터)만 저장됩니다.

.gitattributes 파일 추천 내용

# Unreal Engine binary assets
*.uasset filter=lfs diff=lfs merge=lfs -text
*.umap filter=lfs diff=lfs merge=lfs -text
*.fbx filter=lfs diff=lfs merge=lfs -text

# Audio assets
*.wav filter=lfs diff=lfs merge=lfs -text
*.mp3 filter=lfs diff=lfs merge=lfs -text
*.ogg filter=lfs diff=lfs merge=lfs -text
*.flac filter=lfs diff=lfs merge=lfs -text

# Source art / authoring files
*.psd filter=lfs diff=lfs merge=lfs -text
*.blend filter=lfs diff=lfs merge=lfs -text

# Optional: only if your project actually uses these
*.bank filter=lfs diff=lfs merge=lfs -text
*.bk2 filter=lfs diff=lfs merge=lfs -text
*.3ds filter=lfs diff=lfs merge=lfs -text
*.xcf filter=lfs diff=lfs merge=lfs -text

# 참고
# PNG/JPG는 기본 LFS 대상이 아닙니다. 일반 이미지 파일까지 전부 LFS에 넣으면 용량과 대역폭을 빠르게 소모할 수 있습니다.
# .exe, .dll, .vcxproj 같은 빌드 산출물/생성 파일은 보통 LFS가 아니라 .gitignore 대상입니다.

LFS 추적 확인

LFS 성공 확인 커맨드

git lfs ls-files            # LFS로 관리되는 파일 목록이 뜨면 = 성공
git lfs ls-files -s         # 파일 옆에 '크기'까지 표시 (로컬 LFS 파일 용량)
git lfs ls-files --all -l -s  # 모든 커밋(--all)의 LFS 객체 + 해시(-l) + 크기(-s)

LFS 추적 확인

git lfs track
git status

git lfs track → 현재 LFS 추적 대상 패턴 목록 확인.
git status → .gitattributes가 스테이징됐는지, 애셋이 LFS로 잡혔는지 확인.

clone 대신 개인 무료 클라우드 + fetch/pull 적극 활용

대용량 파일들을 푸시/풀 할 때는 GitHub 대역폭/스토리지가 큰 폭으로 사용됩니다. 그리고 에셋들중에서는 용량이 큰것들이 많아서 clone 할경우 많은 대역폭/스토리지가 사용되기 때문에 이것을 그나마 우회 할 수 있는 방법이 에셋들은 구글 드라이브로 서로 공유해서 코드만 fetch/pull 하면 대역폭/스토리지를 크게 아낄 수 있게 됩니다.

Git(깃) LFS(Large File Storage) | Unreal Engine(언리얼 엔진)의 프로젝트들 Git LFS 로 관리 하기 (다른 큰 프로젝트들도 해당됨 like Unity)