프로젝트 개발을 신나게 마치고 평소처럼 git push origin main 명령어를 입력했는데, 콘솔 창 가득 시뻘건 에러 메시지가 쏟아져 나온 적 있으신가요? 저도 처음 딥러닝 모델 가중치 파일(.pth)이나 고화질 영상 소스를 깃허브에 올리려다 “remote: error: GH001: Large files detected” 경고를 마주했을 때 정말 눈앞이 캄캄했답니다. 😅
뒤늦게 .gitignore에 파일명을 적어보거나 파일을 폴더에서 지우고 다시 커밋해봐도 푸시는 여전히 거절되죠. 그 이유는 Git이 이전 커밋 기록 속에 그 무거운 파일을 그대로 간직하고 있기 때문이에요. 오늘은 이 지긋지긋한 대용량 파일 에러의 근본적인 원인과 함께, Git LFS(Large File Storage)를 활용해 안전하게 푸시하고 이미 꼬여버린 커밋 히스토리를 말끔하게 정리하는 방법을 하나씩 차근차근 알려드릴게요!
1. 왜 깃허브는 내 파일을 거부할까? (용량 정책 분석) 🤔
GitHub은 전 세계 개발자들이 코드를 공유하는 공간인 만큼 저장소 서버의 안정성을 위해 파일 크기를 엄격하게 제한하고 있어요. 텍스트 위주의 코드 파일은 수십 킬로바이트 수준이지만, 데이터셋이나 압축 파일, 고화질 미디어 파일은 금방 수백 메가바이트를 넘어가기 때문이죠.
깃허브가 정한 단일 파일 용량 규칙은 딱 두 가지만 기억하시면 돼요. 50MB를 넘으면 노란색 경고(Warning)를 보내지만 푸시는 허용되고, 100MB를 단 1바이트라도 초과하면 에러(Error)와 함께 푸시 자체가 즉시 차단됩니다.
GitHub 단일 파일 및 저장소 용량 제한 기준
| 구분 | 제한 기준 | 동작 방식 | 권장 해결책 |
|---|---|---|---|
| 50MB 이하 | 안전 범위 | 경고 없이 일반 커밋 및 푸시 성공 | 일반 Git 관리 |
| 50MB ~ 100MB | 주의 권고 | 푸시는 성공하지만 터미널에 Warning 출력 | Git LFS 도입 권장 |
| 100MB 초과 | 절대 차단 (Hard Limit) | GH001 에러 발생 및 원격 푸시 전면 거부 | Git LFS 필수 적용 |
| 전체 레포지토리 | 권장 1GB ~ 5GB | 초과 시 클론 속도 저하 및 이메일 알림 수신 | 정기적인 히스토리 청소 |
파일을 로컬에서 삭제하고 새로운 커밋을 추가하더라도 이미 이전 커밋에 100MB 파일이 기록되어 있다면 푸시는 계속 실패합니다. Git은 히스토리 전체의 무결성을 검증하기 때문이에요!
2. 정석대로 해결하기: Git LFS 설치 및 트래킹 가이드 📦
그렇다면 100MB가 넘는 파일은 깃허브에 영영 올릴 수 없는 걸까요? 당연히 방법이 있죠! 바로 Git LFS(Large File Storage) 확장 프로그램을 사용하는 것이에요. Git LFS는 실제 무거운 파일 본체는 원격 전용 스토리지에 따로 보관하고, 깃 레포지토리에는 가벼운 텍스트 포인터(참조 링크)만 남겨두는 기술이랍니다.
Git LFS를 사용하면 저장소 용량이 비대해지지 않고 동료 개발자가 프로젝트를 클론할 때도 불필요한 대용량 다운로드를 방지할 수 있어 협업 효율이 극대화됩니다.
설치와 적용은 놀라울 정도로 간단해요. 터미널을 열고 다음 순서대로 명령어를 차례대로 입력해 주시면 됩니다.
- Git LFS 프로그램 설치: macOS라면 Homebrew로
brew install git-lfs를 실행하고, Windows는 공식 Git 설치 파일에 기본 포함되어 있어요. - LFS 활성화: 터미널에서
git lfs install명령어를 1회 실행하여 시스템에 등록합니다. - 대용량 확장자 트래킹 등록: 예를 들어 100MB가 넘는 zip 파일을 추적하려면
git lfs track "*.zip"을 입력합니다. - .gitattributes 파일 커밋: LFS 트래킹 설정이 담긴
.gitattributes파일을 먼저 깃에 등록해야 합니다.
📝 터미널 실행 명령어 모음
git lfs install
git lfs track "*.psd" (또는 원하는 확장자 및 특정 파일 경로)
git add .gitattributes
git commit -m "chore: Git LFS 추적 설정 추가"
git add large_file.psd && git commit -m "feat: 대용량 디자인 파일 추가"
3. 이미 커밋해버려서 Push 에러가 났을 때 긴급 탈출법 🛠️
가장 많은 분들이 절망하는 지점이 바로 여깁니다. “이미 git add . 하고 git commit까지 끝냈는데 push가 막혔어요!” 하는 상황이죠. 이럴 때는 대용량 파일이 들어간 시점에 따라 대처 방법이 달라집니다.
상황 A: 바로 직전 커밋(가장 최근 커밋)에만 파일이 들어있는 경우
이 경우는 비교적 수습이 아주 간단해요. git reset 명령어로 커밋만 취소하고 작업 파일은 그대로 둔 채 LFS 트래킹을 걸어주면 됩니다.
1) 커밋 취소하기 (작업 내역은 보존): git reset --soft HEAD~1
2) Git LFS 트래킹 지정: git lfs track "파일명.확장자"
3) 설정 파일 및 대용량 파일 스테이징: git add .gitattributes 파일명.확장자
4) 다시 커밋 후 푸시: git commit -m "feat: LFS 적용 커밋" && git push origin main
상황 B: 여러 커밋 전에 포함되어 히스토리 깊은 곳에 묻혀있는 경우
여러 개의 커밋이 쌓여서 언제 대용량 파일이 들어갔는지 찾기 어렵다면, Git 공식 권장 도구인 git-filter-repo를 사용해 과거의 모든 커밋 히스토리에서 해당 파일 흔적을 완전히 지워야 합니다.
1) 도구 설치: pip install git-filter-repo
2) 문제의 대용량 파일 완전 제거: git filter-repo --path "문제파일경로" --invert-paths
3) 삭제 완료 후 원격 저장소 재연결 및 강제 푸시: git push origin main --force
→ 과거의 모든 커밋 트리가 재작성되면서 100MB 초과 에러가 완벽히 사라집니다!
--force 푸시는 원격 브랜치의 커밋 해시를 바꾸므로, 팀원들과 반드시 일정을 공유하고 작업 전 로컬 브랜치를 별도로 백업해 두는 것이 안전합니다.
4. 내 파일은 일반 푸시가 될까? 용량 판별 도구 🔢
올리려는 파일의 용량이 애매해서 LFS를 적용해야 할지 고민되시나요? 아래 간이 판별기에 파일 크기를 입력하고 단위를 선택해 보세요. GitHub 정책에 맞춰 푸시 가능 여부와 올바른 대처법을 즉시 계산해 드립니다.
🔢 GitHub 파일 업로드 적합성 판별기
5. 실전 사례: 인공지능 모델 파일(180MB) 푸시 대소동 📚
실제 실무에서 어떤 형태로 실수가 발생하고 어떻게 극복하는지 제 경험담을 바탕으로 재구성한 사례를 살펴볼게요. 비슷한 문제를 겪고 계신 분들에게 큰 도움이 될 거예요!
사례 주인공의 당황스러운 상황
- 작업 내용: 머신러닝 학습 모델 결과물인
model_weights.bin(용량 약 180MB)을 커밋함 - 발생 증상:
git push origin main실행 시 GH001 에러와 함께 98%에서 전송 중단 - 첫 번째 오대응: 파일을 로컬에서 삭제하고
git commit -m "remove model"후 재푸시했으나 여전히 동일 에러 발생
올바른 트러블슈팅 해결 과정
1) git log --oneline으로 대용량 파일이 들어간 2개의 커밋을 확인
2) git reset --soft HEAD~2 명령어로 문제 커밋 2개를 한꺼번에 작업 디렉토리 상태로 롤백
3) git lfs track "model_weights.bin" 실행하여 포인터 관리 등록
4) 생성된 .gitattributes 파일과 모델 파일을 함께 git add 및 커밋
최종 결과
- 결과: LFS 객체 업로드 프로그레스 바가 뜨면서 180MB 파일 푸시 100% 성공
- 저장소 상태: GitHub 웹 브라우저에서 파일 옆에 귀여운 'Stored with Git LFS' 뱃지 표시 확인
GitHub 무료 계정의 경우 Git LFS 무료 스토리지 용량은 1GB, 월간 대역폭은 1GB로 제한되어 있어요. 여러 팀원이 빈번하게 클론하고 풀을 받으면 월간 대역폭이 소진되어 LFS 다운로드가 일시 중단될 수 있으니 꼭 모니터링해 주세요!
마무리: 핵심 내용 요약 📝
대용량 파일 에러는 깃의 내부 동작 원리를 조금만 이해하면 당황하지 않고 손쉽게 해결할 수 있는 대표적인 관문이에요. 오늘 다룬 핵심 포인트를 다시 한번 일목요약해 드릴게요.
- 100MB 제한의 벽: GitHub은 단일 파일 100MB 초과 시 GH001 에러로 푸시를 원천 차단합니다.
- 단순 삭제는 무용지물: 파일만 지우고 다시 커밋해도 과거 히스토리에 파일이 남아있으면 푸시할 수 없습니다.
- Git LFS의 정석 활용:
git lfs track "*.확장자"와.gitattributes커밋으로 깔끔하게 포인터 관리하세요. - 이미 커밋된 상태라면: 직전 커밋은
git reset --soft HEAD~1, 과거 깊은 커밋은git-filter-repo를 활용하세요.
GitHub LFS 에러 탈출 핵심 치트시트
자주 묻는 질문 ❓
git add를 하지 않은 새 파일이라면 .gitignore로 간단히 추적을 제외할 수 있습니다. 하지만 이미 깃의 추적 대상(Staged 또는 Committed)이 된 파일은 .gitignore에 적는다고 해서 자동으로 히스토리에서 빠지지 않습니다. 이미 커밋된 파일은 반드시 히스토리 재작성 작업이 필요합니다.git lfs install을 실행하도록 안내해 주세요.
갑작스러운 깃허브 푸시 에러에 당황하셨던 분들에게 이번 글이 시원한 해결책이 되었기를 바랍니다. Git LFS 설정이나 커밋 롤백 과정에서 잘 안 풀리거나 추가로 궁금한 점이 있다면 언제든 편하게 댓글로 남겨주세요~ 😊