GitHub: push 거부 — GH001 Large files detected (100 MB 초과)

안녕하세요, BlueByte입니다. push를 했더니 GitHub이 거부합니다: remote: error: GH001: Large files detected. 로컬 history는 멀쩡한데, 그 안 어딘가에 GitHub이 허용하는 한도보다 큰 파일이 있어서 서버가 push 전체를 거부한 것입니다. 증상은 push가 (pre-receive hook declined)로 끝나면서 GitHub 크기 한도를 넘는 파일을 지목하는 것입니다. 오늘은 한도가 얼마인지, 파일만 지우면 왜 안 되는지, 정확한 객체를 찾는 법, 파일이 어디 있느냐에 따라 두 가지로 고치는 법, 그리고 다시 안 생기게 막는 법까지 짚어보겠습니다.

"GH001: Large files detected"가 뜻하는 것

GitHub은 파일 크기 한도를 서버에서 강제하므로, 아무것도 저장되기 전에 push가 거부됩니다:

remote: error: GH001: Large files detected. You may want to try Git Large File Storage - https://git-lfs.github.com.
remote: error: Trace: 9f8c1a2b3c4d5e6f
remote: error: See https://gh.io/lfs for more information.
remote: error: File models/checkpoint.bin is 210.44 MB; this exceeds GitHub's file size limit of 100.00 MB
To github.com:acme/ml.git
 ! [remote rejected] main -> main (pre-receive hook declined)
error: failed to push some refs to 'github.com:acme/ml.git'

한도는 두 가지가 중요합니다. GitHub은 50 MiB를 넘는 파일에 경고를, 100 MiB를 넘는 파일은 완전히 차단합니다 — 지금 걸린 게 이 차단입니다. (웹 업로드 UI는 별도로 25 MiB에서 막힙니다.) GitHub은 또한 리포지토리를 1 GB 미만, 되도록 5 GB 미만으로 유지하길 권장합니다. 해결책은 파일을 history 안에서 100 MiB 아래로 낮추거나 Git LFS로 옮기는 것입니다.

파일을 지우고 다시 커밋해도 왜 안 되나

파일을 git rm하고 커밋한 뒤 다시 push하고 싶은 게 본능입니다. 하지만 안 됩니다. Git은 전체 history에 걸쳐 모든 파일의 모든 버전을 저장하고, push는 서버에 아직 없는 커밋을 전부 보냅니다. 큰 blob은 앞선 커밋에 여전히 있으므로 pre-receive hook이 계속 그것을 보고 계속 거부합니다. 고치려면 그 파일을 도입한 커밋에서 제거해야 합니다 — tip에서만 지우는 게 아니라요.

어느 커밋의 어떤 파일이 큰지 찾기

오류가 파일을 지목해 주지만, 여러 개라면 history에서 가장 큰 blob들을 나열합니다:

git rev-list --objects --all \
  | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' \
  | awk '/^blob/ {print $3, $4}' | sort -n | tail -5

54182391 src/data/sample.csv
220612334 models/checkpoint.bin

크기 단위는 바이트라서 220612334는 약 210 MB — 이게 범인입니다. 경로를 적어 두면 다음 단계에서 겨냥합니다.

최신 커밋에만 있다면: 빼고 다시 커밋

방금 파일을 커밋했고 브랜치를 아직 공유하지 않았다면, 커밋 하나로 끝납니다:

git rm --cached models/checkpoint.bin
echo "models/checkpoint.bin" >> .gitignore
git commit --amend -C HEAD
git push

--cached는 커밋에서 파일을 빼되 디스크에는 남깁니다; amend는 tip 커밋 하나를 blob 없이 다시 씁니다. 파일이 최근 여러 커밋에 걸쳐 추가됐다면 각 커밋을 손보는 것보다 아래의 migrate 방식이 안전합니다.

history 깊이 묻혀 있다면: git lfs migrate로 재작성

blob이 여러 커밋 전에 있다면, history를 다시 써서 한 번에 Git LFS로 옮깁니다:

git lfs migrate import --include="*.bin" --everything
git push --force-with-lease

git lfs migrate import는 history 전반에서 해당 파일들을 작은 LFS pointer 파일로 바꾸고 그 패턴을 .gitattributes에 기록합니다. 그래서 실제 바이트는 Git 객체가 아니라 LFS에 놓입니다. --everything은 모든 브랜치와 태그를 포함합니다. 이건 history를 다시 씁니다 — 변경 이후 모든 커밋의 SHA가 새로 바뀝니다 — 그래서 파괴적입니다: force-push해야 하고, 그 clone을 가진 다른 사람은 다시 clone하거나 hard-reset해야 합니다. 공유 브랜치에서 돌리기 전에 협의하세요. 파일을 보관하는 대신 아예 지우고 싶다면 git filter-repo --path models/checkpoint.bin --invert-paths로 제거합니다.

실제 사례: 지난주 커밋된 210 MB 체크포인트

동료가 다섯 커밋 전에 models/checkpoint.bin(210 MB)을 커밋해 feature 브랜치에 push했다가 GH001로 실패했습니다. 브랜치가 아직 공유 전임을 확인하고, git lfs install로 Git LFS를 설치한 뒤 git lfs migrate import --include="*.bin" --everything을 돌립니다. 명령이 그 다섯 커밋을 다시 쓰고, .gitattributes에 *.bin filter=lfs diff=lfs merge=lfs -text를 추가하며, blob 자리에 pointer를 남깁니다. 이제 git push --force-with-lease가 성공합니다 — GitHub은 pointer(수백 바이트)를 받고 실제 파일은 LFS에 저장합니다.

push가 성공하고 파일이 LFS로 추적되는지 확인

Git이 이제 그 파일을 LFS 객체로 다루는지 확인합니다:

git lfs ls-files

a1b2c3d4e5 * models/checkpoint.bin

여기 한 줄이 나오면 그 파일은 raw blob이 아니라 LFS가 뒷받침하는 pointer입니다. git cat-file -s HEAD:models/checkpoint.bin이 작은 크기 — pointer는 약 130 바이트입니다 — 를 돌려주면 history가 더 이상 전체 파일을 지고 있지 않다는 확인입니다.

큰 파일을 애초에 Git에 넣지 않기

무엇이 LFS에 속하는지 미리 정하고 첫 커밋 전에 추적하세요: git lfs track "*.bin"이 .gitattributes 규칙을 써 두어 새 큰 파일이 raw blob으로 Git history에 들어오지 않게 합니다. 빌드 산출물, 데이터셋, 모델 파일은 .gitignore에 넣어 실수로 커밋되지 않게 합니다. 버전 관리가 필요 없는 릴리스 바이너리는 커밋하지 말고 GitHub Release에 첨부하세요. 약 50 MB를 넘는 파일을 막는 pre-commit hook은 이 실수를 push 거부가 되기 전에 로컬에서 잡아 줍니다.

"pack exceeds maximum allowed size"와는 어떻게 다른가

GH001은 100 MiB를 넘는 단일 파일에 대한 것입니다. remote: fatal: pack exceeds maximum allowed size 같은 다른 거부는 한 파일이 아니라 push 전체의 크기에 대한 것입니다. 메시지가 파일과 파일당 한도를 지목하면 GH001이고 LFS나 history 재작성이 해결책입니다; pack 크기를 지목하면 한 번에 커밋을 더 적게 push하거나 push를 작은 덩어리로 나누세요.