Live/17/GitLFS

일시 : [2025-07-22] 화요일 (14:00 - 15:50)

학습 기록을 위하여 강의 수강 후 별도로 정리한 이하 내용에 대하여
대부분의 참고 이미지, 개념 설명, 문제 풀이는 해당 강의 자료에서 발췌.
또는 직접 실습한 결과를 별도로 사진 캡처 및 동영상으로 기록함.

(출처: 스파르타코딩 내일배움캠프)

 

< 목차 >

1. 깃허브 무료버전 관리 시 파일 제한

2. 조치

3. gitignore

4. Git Large File Storage (Git LFS)
4-1. 주의사항
4-2. 월드파티션 기능 해제 방법
5. clone 대신 개인 무료 클라우드 + fetch/full 적극 활용
5-1. 해결 방법
6. 팀플 동안에 커밋 시 반드시 해야 할 일들
6-1. 커밋 전 반드시 변경사항(변경/추가된 파일들)들을 천천히 살펴보기
6-2. 변경사항 중 본인이 작업한 내용이 아니라면 반드시 제거
6-3. 에셋 파일을 올릴 때는 소스코드와 같이 올리지 말기
6-4. 푸시 전에는 반드시 플레이 테스트 진행
6-5. 무슨 이유에서든 커밋을 쌓아두지 말기

7. 별도 첨부

< 내용 >

1. 깃허브 무료버전 관리 시 파일 제한

하나의 파일이 100MB 초과하는 경우 커밋 혹은 푸시가 차단된다.

그리고 핸드폰 요금제처럼 매달 Storage 10GB, Bandwidth 10GB가 주어진다.

해당 용량을 모두 소진하면 더 이상 쓸 수 없다.

 

언리얼 프로젝트는 텍스처, 사운드, 모델링 파일, 레벨 에셋의 경우 100MB를 넘는 경우가 많다.

최종 프로젝트 기준 50에서 80GB 정도.

 

대용량 에셋을 자주 푸시할 경우 할당받은 스토리지 10GB를 다 쓰게 된다.

클론을 자주 시도할 경우에도 무료버전에 할당된 대역폭 10GB를 모두 소진한다.

대역폭을 모두 사용하면 다음 달까지 더 이상 푸시나 클론이 되지 않는다.

 

2. 조치

".gitignore"파일을 통해 필요 없는 폴더나 파일을 무시하도록 해야 한다.

그리고 Git Large File Storage를 이용하여 대용량 파일을 우회 관리한다.

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

 

3. gitignore

- 파일 내용

# Visual Studio 2015 user specific files
.vs/
.vsconfig

# Jetbrain Rider
.idea/

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

# Precompiled Headers
*.gch
*.pch

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

# Fortran module files
*.mod
*.smod

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

# Executables
*.exe
*.out
*.app
*.ipa
Output
Engine/x64
Client/x64
.vs

# 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/*

# Prerequisites
*.d

 

".gitignore" 파일을 만들 때 파일 확장명을 반드시 확인.

ex) “.gitignore.txt”로 만드는 실수 빈번함.

".uproject" 파일과 같은 폴더에 ".gitignore" 파일이 있도록 해야 함.

 

무시하고 싶은 파일이 이미 리모트에 올라갔다면, .gitignore에 작성해도 효과 없음.

이미 올라간 파일을 모두 내리고, ".gitignore" 파일을 수정 후 커밋/푸시해야 함.

 

리모트에 .gitignore 파일 수정 커밋이 푸시되어 있고,

로컬에서 무시 파일을 올리려 하면 푸시 차단됨.

 

4. Git Large File Storage (Git LFS)

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

 

- ".gitattributes" 파일 내용

# UE file types
*.uasset filter=lfs diff=lfs merge=lfs -text
*.umap filter=lfs diff=lfs merge=lfs -text
# Visual Studio
*.vcxproj filter=lfs diff=lfs merge=lfs -text
# Binaries
*.exe filter=lfs diff=lfs merge=lfs -text
*.dll filter=lfs diff=lfs merge=lfs -text
*.rcc filter=lfs diff=lfs merge=lfs -text
# Contents
*.bank filter=lfs diff=lfs merge=lfs -text
*.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
*.fbx filter=lfs diff=lfs merge=lfs -text
*.3ds filter=lfs diff=lfs merge=lfs -text
*.xcf filter=lfs diff=lfs merge=lfs -text
*.jpg filter=lfs diff=lfs merge=lfs -text
*.png filter=lfs diff=lfs merge=lfs -text
*.ico filter=lfs diff=lfs merge=lfs -text
*.icns filter=lfs diff=lfs merge=lfs -text
*.bk2 filter=lfs diff=lfs merge=lfs -text
.txt filter=lfs diff=lfs merge=lfs -text
*.psd filter=lfs diff=lfs merge=lfs -text

[공식 사이트]에서 다운로드. 설치까지 진행.

로컬 레포지토리 폴더 > 경로창 클릭 후 “CMD” 작성. 
엔터 치면 해당 디렉터리에서 CMD 창이 실행됨.

git lfs install 명령어 타이핑 후 엔터.

git lfs install

git lfs track “*.psd” 명령어 타이핑 후 엔터.

.gitattributes 파일이 생성되며, 자동으로 .psd 파일들 전부를 LFS 대상 파일로 지정되게끔 하는 구문이 작성됨.

위의 .gitattributes 파일 내용을 ".gitattributes" 복사 붙여 넣기.

git lfs track “*.psd”

이후, 커밋 / 푸시까지 진행해야 함.

 

4-1. 주의사항

Git LFS 사용 시 되도록이면 월드파티션 기능을 해제.

Git LFS 주의사항 - Git LFS 사용 시 되도록이면 월드파티션 기능을 해제.
UE5에서 도입된 레벨 월드파티션의 Actor Per File 기능과 문제 될 수 있음.
UE4에서는 레벨에 배치된 모든 액터가 하나의 레벨 파일에 저장되었음.
두 팀원이 레벨 속 다른 액터를 수정하더라도, 하나의 레벨 파일이 수정되므로 충돌이 발생했음.
Actor Per File은 레벨 속 액터마다 하나의 파일(. uasset)로 관리되게끔 해주는 기능.
따라서 UE4에서의 문제는 사라졌으나, Git LFS와의 궁합에서 문제가 생김.
레벨 속 액터마다 하나의 파일로 관리되면서 해당 파일이 Git LFS로 커밋/푸시가 된다면
해당 파일은 Git LFS 서버 히스토리에서 영원히 지울 수 없어짐.

 

4-2. 월드파티션 기능 해제 방법

가급적이면 레벨을 만들 때, “Open”이라는 단어가 들어가지 않은 레벨을 만들기를 추천.
이 레벨들은 기본적으로 월드파티션을 지원함.

 

프로젝트 세팅 내 월드 파티션에 New Maps Enable World Partition 옵션을 비활성화

 

이미 월드파티션이 적용된 레벨을 만들어서 진행 중이라면,
World Settings > World Partition Setup > Enable Streaming 체크 해제.

 

World Settings > World Partition Setup > Enable Streaming 체크 해제하면

Disable World Partition 버튼이 열림.
클릭해서 완전히 기능 제거.

 

Use External Actors를 비활성화

 

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

용량제한
이번 팀플과제에서 각 팀별로 사용할 수 있는 GitHub 제한은 20GB 정도.
Fab과 같은 곳에서 대용량 파일을 올려야 할 때는, 담당 튜터님과 상의 후 진행.

모든 조원이 필요할 때마다 클론 하면 요금제가 녹아서 사라짐
에셋을 구비하고 리모트 레포지토리에 푸시한 상태. 레포지토리 크기는 대략 20GB.
조원이 7명이라면, 한 번씩만 clone 받아도 140GB의 대역폭이 사용됨.
최초에 한 번은 그렇다 쳐도, 그 뒤로도 뭔가 초기화 작업이 필요하다면 클론 해야 함.
최소 140GB 이상의 대역폭이 사용될 것으로 예상할 수 있음.

 

5-1. 해결 방법

프로젝트에 필요한 애셋을 더 추가할 필요 없을 정도로 최대한 모으기
가능하다면 필요한 애셋만 언리얼의 Migrate 기능을 활용.

깃 관리자 한 명이 애셋들을 리모트 레포지토리에 커밋/푸시.

성공하면 깃 관리자는 성공한 로컬 레포지토리를 압축
이때 반드시 .git 폴더가 포함되어야 함.

압축된 파일을 구글 클라우드나 네이버 박스 등의 무료 클라우드에 업로드.
팀원들은 해당 무료 클라우드에 접속하여 다운.

리소스는 무료드라이브로 받고, 소스코드만 fetch/pull 받으므로 요금제를 훨씬 덜 쓸 수 있다.

 

6. 팀플 동안에 커밋 시 반드시 해야 할 일들

6-1. 커밋 전 반드시 변경사항(변경/추가된 파일들)들을 천천히 살펴보기

대부분의 문제가 커밋을 아무 생각 없이 작성하기 때문에 발생한다.
1~2번 정도는 실수라고 볼 수 있지만, 3번부터는 고의.
제대로 작성했는지, 다른 파일을 건들지는 않았는지 등등 진지하게 임하기.

 

6-2. 변경사항 중 본인이 작업한 내용이 아니라면 반드시 제거

본인은 소스코드만 수정했고, 애셋은 건든 적 없다면 .uasset 파일의 변경사항은 내린다.
딱 본인이 작업한 내용만 올리고, 정확한 커밋메시지 작성

 

".uasset" 이나 ".umap" 파일은 히스토리를 볼 수 없으므로 반드시 충돌 나지 않도록 해야 한다. 잠금해제 주의

 

6-3. 에셋 파일을 올릴 때는 소스코드와 같이 올리지 말기

스켈레탈 메시나 레벨 에셋 같은 애셋 파일들을 푸시할 때는 순수하게 에셋 파일들만 올리기.
소스코드는 다른 커밋으로 나눠서 올리는 게 좋다.

 

6-4. 푸시 전에는 반드시 플레이 테스트 진행

가끔 충돌 나는 게 두려워서 플레이 테스트도 안 하고 올려버리는 경우가 있다.
그건 그냥 팀원들에게 수류탄 까서 던지는 것과 같은 꼴.

 

6-5. 무슨 이유에서든 커밋을 쌓아두지 말기

리모트로 푸시하는 것이 겁난다거나, 아직 미완성이랍시고 완벽을 기다린다거나..
각양각색의 이유로 커밋을 10개 이상씩 쌓아두는 경우
다른 사람들에게는 엄청난 소스코드를 한 번에 분출하게 되고,
본인에게는 충돌 처리라는 아픔이 남으므로 모두에게 해롭다.

 

7. 별도 첨부

Git LFS로 언리얼 프로젝트 업로드하는 전체 과정 (CMD 기준)

 

7-1. Git LFS 설치 (한 번만 하면 됨)

Git LFS가 아직 설치 안 되어 있다면

git lfs install

 

설치가 잘 됐으면

git lfs version

이전에 "git lfs install" 내용을 한번 했어서 "git lfs version"을 입력하니 아래와 같이 출력되었다.

"git-lfs/3.6.1 (GitHub; windows amd64; go 1.23.3; git ea47a34b)"이런식으로 뜬다.

 

7-2. Git 저장소 초기화 (이미 했으면 건너뛰기)

cd [프로젝트 폴더 경로]
git init

이미 .git 폴더가 있다면, git init은 다시 안 해도 된다.

 

해당 폴더에 .git 폴더가 있는지 확인하는 방법

dir /a

이 명령어를 CMD에서 치면 숨김 파일 포함해서 폴더 내 목록을 보여준다.

이미 .git 폴더가 있는 경우 (초기화 안 해도 되는 상태)

.git 폴더가 없다면? 그땐 Git 저장소로 인식되지 않기 때문에 반드시 git init을 먼저 해줘야 한다.

 

"dir /a"을 입력하니 아래와 같이 출력되었다.

 

7-3. Git LFS로 추적할 파일 형식 지정

언리얼에서 많이 쓰는 .uasset, .umap, .fbx, .png 등을 LFS로 관리하겠다면

git lfs track "*.uasset"
git lfs track "*.umap"
git lfs track "*.fbx"
git lfs track "*.png"

그럼 .gitattributes 파일이 자동 생성되고, LFS로 어떤 파일을 추적할지 설정된다.

 

아래와 같이 출력되었다.

 

7-4. 원격 저장소 연결 (GitHub 저장소(Repository)와 연결)

리포에 로컬 프로젝트 연결

git remote add origin https://github.com/yourusername/your-repo.git

 

이미 리포지토리 클론을 받아서 업로드하는 중이라 이 과정은 하지 않았다.

 

7-5. 파일 추가

git add .를 안 하면 git commit 해도 변경된 파일이 커밋되지 않는다.

즉, 수정은 했지만 Git은 그걸 모른 척하고, 커밋은 "아무것도 바뀐 게 없다"는 식으로 넘어간다.

Git은 파일을 커밋할 때 "스테이징 영역"에 올라간 파일만 포함한다.

git add는 그 스테이징 영역에 변경된 파일을 "올리는" 명령이다.

 

작업 디렉터리 : 내가 실제 수정한 파일 (변경사항 존재)

스테이징 영역 : git add를 통해 올라간 파일

커밋(commit) : 스테이징 영역의 내용만 저장

 

git add . 후 git commit을 하도록 한다.

git add .

"."는 전체 파일을 추가하는 뜻

 

기존에 간단히 C++프로젝트로 할 때는 아무 문구가 없었는데 이번에는 아래와 같이 출력되었다.

찾아보니 문제 되지 않는 Warning이라길래 넘어가기로 했다.

 

7-6. 작업 디렉터리 상태 확인

어떤 파일이 수정됐고, 어떤 파일이 스테이징 됐는지 확인할 수 있다.

지금 내 프로젝트에서 어떤 파일이 git add로 올라갔는지, 아직 올라가지 않았는지 보는 과정으로

커밋 전에 Git 상태 점검을 하면 실수를 줄일 수 있다.

git status

 

7-7. 커밋

git commit -m "Initial Unreal project upload with Git LFS"

문구는 남기고 싶은 대로 한다.

"Add Git LFS tracking for Unreal project"이 될 수도 있겠다.

출력 내용은 길어서 생략.

 

7-8. GitHub로 푸시

main 브랜치가 아니라면 master나 현재 브랜치 이름으로 대체한다.

git push origin main

처음 푸시하는 거라면 아래처럼 강제로 브랜치 연결

git push -u origin main

 

이제, 용량에 따라 업로드하는 데 걸리는 시간이 달라진다.

정상적으로 업로드되었다면 아래와 같이 출력될 것이다.

 

최초 커밋인 1에서 2로 변경되었다.

 

커밋 메시지대로 잘 올라와 있다.

 

7-9. 추가 작업 시 Git 명령어 순서 (매번 쓰는 루틴)

언리얼에서 파일 수정 → GitHub에 반영하고 싶을 때

Git은 변경된 파일만 추적하기 때문에, 같은 파일이더라도 수정한 부분만 반영된다.

.uasset이나 .umap 같은 파일은 Git LFS가 추적해서 자동 처리된다.

처음처럼 track이나 init은 다시 안 해도 된다.

 

변경된 모든 파일을 Git에 올릴 준비

git add .

 

변경 내용을 커밋함 (= 저장 + 메모 남김)

git commit -m "작업 내용 간단히 작성"

 

GitHub 원격 리포지토리에 업로드

git push origin main

 

7-10. 리포지토리에 있는 내용을 로컬에서 최신으로 받기

git pull origin main

최신 내용을 받아오고, 그다음 git add .를 하고 다시 커밋 그리고 푸시하면 된다.

 

7-11. 커밋 메시지를 다시 확인

git log -1

이 명령어를 치면 방금 커밋한 메시지와 함께 커밋 해시, 작성자, 날짜 등을 확인할 수 있다.

-1은 가장 최근 커밋 1개만 보여주라는 뜻.

아래와 같이 출력되었다.

 

아래와 같이 입력하면 메시지 내용만 깔끔하게 출력된다.

git log -1 --pretty=%B

아래와 같이 출력되었다.