[Git] GitHub 100MB 이상 대용량 파일 업로드 완벽 가이드 (Git LFS, 장단점, 실습, 상황별 처리 전략)

1. 들어가며: "왜 내 코드는 Push가 안 될까?"

머신러닝 모델 가중치 파일(200MB), 게임 개발용 에셋 파일(500MB), 혹은 대용량 데이터셋(1GB). 프로젝트를 진행하다 보면 필연적으로 용량이 큰 파일을 다루게 됩니다. 기분 좋게 코딩을 마치고 git push를 날렸는데, 터미널에 아래와 같은 빨간색 에러 메시지가 뜬 적 있으신가요?

remote: error: GH001: Large files detected. You may want to try Git Large File Storage.
remote: error: File model.bin is 157.92 MB; this exceeds GitHub's file size limit of 100.00 MB

GitHub은 성능 유지를 위해 100MB 이상의 단일 파일 업로드를 엄격하게 차단합니다. 더 끔찍한 것은, 에러를 보고 놀라서 파일을 지우고 다시 커밋(Commit)하더라도, "과거의 커밋 내역(히스토리)"에 이미 큰 파일이 남아있기 때문에 계속해서 Push가 거부된다는 점입니다.

이 글에서는 GitHub의 대용량 파일 정책을 짚어보고, 이를 해결하기 위한 구원자 'Git LFS(Large File Storage)'의 작동 원리와 사용법, 그리고 이미 커밋해버린 대용량 파일을 히스토리에서 지워버리는 방법(BFG Repo-Cleaner)까지 완벽하게 총정리해 드립니다.

---

2. GitHub의 파일 크기 정책 및 한계

GitHub에 파일을 올릴 때는 다음의 용량 제한을 반드시 기억해야 합니다.

• 50MB 이하: 정상 업로드
• 50MB ~ 100MB 미만: 업로드는 되지만, 터미널에 "파일이 너무 큽니다"라는 경고(Warning) 메시지가 뜹니다.
• 100MB 이상: 업로드가 완전히 차단(Error)됩니다.
• 25MB 이상 (웹 브라우저): 터미널(git push)이 아닌 GitHub 웹사이트에서 직접 파일을 드래그 앤 드롭할 때는 한도가 25MB로 훨씬 빡빡합니다.

 

2-1. 왜 100MB로 제한할까?

Git은 텍스트 코드의 '변경 사항(Diff)'을 추적하는 데 최적화된 시스템입니다. 이미지, 영상, 실행 파일(.exe) 같은 바이너리 파일은 단 1픽셀만 바뀌어도 Git은 아예 새로운 파일로 인식합니다. 이런 대용량 파일이 쌓이면 저장소(Repository) 용량이 폭발적으로 늘어나고, 누군가 저장소를 Clone(다운로드)할 때 엄청난 시간과 메모리를 낭비하게 됩니다.

 

---

3. Git LFS (Large File Storage)란? (개요 및 작동 원리)

100MB가 넘는 파일을 꼭 올려야 한다면 Git LFS를 사용해야 합니다.

 

3-1. 작동 원리: '포인터(Pointer)' 메커니즘

Git LFS의 원리는 아주 천재적입니다. 대용량 파일을 Git 저장소에 직접 넣는 대신, 진짜 대용량 파일은 별도의 LFS 외부 서버에 올리고, Git 저장소에는 그 파일의 '주소표표(Pointer 텍스트 파일, 약 130바이트)'만 남겨두는 방식입니다.

사용자가 평소처럼 git push를 하면, LFS 훅(Hook)이 작동하여 큰 파일을 빼돌려 LFS 서버로 보내고, 깃허브에는 가벼운 텍스트 포인터만 올라가게 됩니다. 나중에 누군가 git clone을 하면, Git LFS가 포인터를 읽고 알아서 진짜 대용량 파일을 다운로드해 줍니다. 개발자의 작업 방식(add, commit, push)은 평소와 100% 동일합니다.

 

---

4. 특징 및 장단점

 

4-1. ✅ 장점 (Pros)

• 저장소 경량화: Git 저장소 본연의 속도와 쾌적함을 유지할 수 있습니다.
• 워크플로우 유지: 기존의 Git 명령어를 그대로 사용하므로 러닝 커브가 낮습니다.
• 부분 다운로드(Lazy Download): 필요한 버전의 대용량 파일만 다운받으므로 대역폭 낭비를 줄입니다.

 

4-2. ❌ 단점 및 한계 (Cons)

• 무료 할당량(Quota) 제한: GitHub Free 플랜 기준으로 LFS는 저장 공간 1GB, 다운로드 대역폭(Bandwidth) 1GB/월만 무료로 제공됩니다. 특히 대역폭이 순식간에 고갈될 수 있으며, 초과 시 월 $5의 데이터팩을 추가 구매해야 합니다.
• 팀원 전원 설치 필수: LFS로 추적된 파일이 있는 저장소는 협업하는 모든 팀원이 컴퓨터에 git-lfs를 설치해야 합니다. 안 그러면 진짜 파일 대신 130바이트짜리 텍스트(포인터) 파일만 열리게 됩니다.

 

---

5. [실전 1] 신규 대용량 파일 올리기 (Push 전)

아직 커밋을 하기 전이라면 방법은 아주 간단합니다.

5-1. Step 1. Git LFS 설치 및 초기화

# macOS (Homebrew)
brew install git-lfs

# Ubuntu/Linux
sudo apt install git-lfs

# 설치 후 내 컴퓨터에 LFS 적용 (최초 1회)
git lfs install

 

5-2. Step 2. 관리할 파일 지정 (Track)

100MB가 넘는 파일이나 확장자를 지정해 줍니다.

# 특정 확장자 전체 지정
git lfs track "*.exe"
git lfs track "*.mp4"

# 특정 파일 하나만 지정
git lfs track "models/large_model.bin"

 

5-3. Step 3. 평소처럼 Commit 및 Push

위 명령어를 치면 .gitattributes라는 파일이 생성됩니다. 이 파일을 반드시 먼저 커밋해야 합니다.

# 1. 속성 파일 먼저 추가
git add .gitattributes

# 2. 대용량 파일 추가
git add models/large_model.bin

# 3. 커밋 및 푸시
git commit -m "feat: 대용량 머신러닝 모델 추가"
git push origin main

성공 확인: Push를 할 때 Uploading LFS objects... 라는 문구가 터미널에 뜨면 정상적으로 외부 서버로 올라간 것입니다.

 

---

6. [실전 2] 이미 Commit해서 에러가 났을 때 (Push 후)

이미 git commit을 해버려서 Push가 거부당하고 있다면, 과거의 커밋 히스토리를 뜯어고쳐야 합니다. 이 경우 Java 기반의 BFG Repo-Cleaner 도구를 사용하는 것이 가장 빠릅니다.

 

6-1. Step 1. BFG 다운로드 및 실행

1. BFG Repo-Cleaner 공식 사이트에서 bfg-x.x.x.jar 파일을 다운로드합니다. (Java 설치 필요)
2. 문제가 되는 저장소 폴더에서 터미널을 열고 아래 명령어를 쳐서 100MB 이상 파일을 히스토리에서 날려버립니다.

# 100MB가 넘는 파일의 커밋 로그를 전부 삭제
java -jar bfg-1.14.0.jar --strip-blobs-bigger-than 100M

💡 에러 발생 시: 만약 does the repo need to be packed? 라는 에러가 뜬다면, 아래 명령어를 먼저 치고 위 명령어를 다시 실행하세요.

git reflog expire --expire=now --all && git gc --prune=now --aggressive

 

6-2. Step 2. 변경 사항 덮어쓰기

이제 찌꺼기가 지워졌으니 강제로 GitHub에 밀어 넣습니다.

git push --force origin main

이후 5번 항목([실전 1])으로 돌아가서 git lfs track을 설정하고 파일을 다시 안전하게 업로드하시면 됩니다.

 

---

7. 한 눈에 비교: 상황별 대용량 파일 처리 전략

내가 처한 상황에 따라 어떤 도구를 써야 할지 직관적으로 비교해 드립니다.

현재 상황	필요한 목적	추천 도구 / 명령어	난이도
아직 커밋 안 했음	파일을 안전하게 올리고 싶다	Git LFS (git lfs track)	⭐ 낮음
이미 커밋해버림	파일을 살려서 LFS로 넘기고 싶다	LFS Migrate (git lfs migrate import)	⭐⭐ 중간
이미 커밋해버림	쓸데없는 파일이라 히스토리에서 완전 삭제하고 싶다	BFG Repo-Cleaner (--strip-blobs-bigger-than 100M)	⭐⭐⭐ 높음
파일이 2GB가 넘음	GitHub의 용량 한계를 벗어났다	AWS S3, Google Drive, Hugging Face Hub	⭐⭐ 중간

 

---

8. 마치며

"100MB 에러"는 개발자라면 누구나 한 번쯤 겪는 통과의례입니다. 하지만 이 문제를 수습하기 위해 과거의 커밋 히스토리를 조작하는 일은 매우 위험하며, 자칫 팀원들의 코드를 망가뜨릴 수도 있습니다.

가장 좋은 방법은 애초에 큰 파일이 커밋되지 않도록 예방하는 것입니다. 프로젝트를 시작할 때 반드시 .gitignore 파일에 빌드 산출물(build/), 로그 파일(*.log), 대용량 데이터(*.csv, *.mp4)를 등록해 두는 습관을 들이세요. 만약 꼭 올려야 하는 에셋이나 모델이 있다면, 커밋을 하기 전 가장 먼저 git lfs track을 세팅하는 꼼꼼함이 여러분의 소중한 퇴근 시간을 지켜줄 것입니다! 🚀