[Git] git-filter-repo로 히스토리에서 제거하기

안녕하세요. 수석 IT 테크 블로거입니다.

개발 프로젝트를 진행하다 보면, 무심코 포함된 고화질 이미지, 머신러닝 모델 파일(.h5, .pth), 혹은 데이터베이스 덤프 파일 등 대용량 파일 때문에 GitHub Push가 거부되는 상황을 마주하게 됩니다. 오늘은 많은 주니어 개발자분들이 당황스러워하는 GitHub 100MB 용량 제한 에러(GH001)를 해결하고, git-filter-repo를 통해 Git 히스토리를 깔끔하게 정리하는 방법을 상세히 다루겠습니다.

---

[Git] GitHub Push 에러 해결: 100MB 이상 대용량 파일 삭제 및 히스토리 정리 (git-filter-repo 완벽 가이드)

1. 문제 상황: "Large files detected" 에러 발생

열심히 코드를 작성하고 기분 좋게 git push를 입력했는데, 갑자기 터미널에 붉은색 에러 메시지가 쏟아지는 경험, 다들 한 번쯤 있으실 겁니다. 특히 아래와 같은 메시지가 뜬다면, 이는 GitHub의 단일 파일 용량 제한(100MB)을 초과했기 때문입니다.

remote: error: See https://gh.io/lfs for more information.
remote: error: File data/big_dataset.csv is 133.58 MB; this exceeds GitHub's file size limit of 100.00 MB
remote: error: GH001: Large files detected. You may want to try Git Large File Storage - https://git-lfs.github.com.
To https://github.com/username/repo.git
 ! [remote rejected] main -> main (pre-receive hook declined)
error: failed to push some refs to 'https://github.com/username/repo.git'

왜 이런 일이 발생할까요?

GitHub는 저장소의 퍼포먼스와 안정성을 위해 100MB가 넘는 단일 파일의 업로드를 차단합니다. 50MB가 넘으면 경고를 주고, 100MB가 넘으면 아예 Push 자체를 막아버립니다.

흔한 오해: ".gitignore에 추가하면 되지 않나요?"

많은 분들이 이 에러를 보고 황급히 해당 파일을 삭제하거나 .gitignore에 추가한 뒤 다시 커밋을 시도합니다. 하지만 에러는 사라지지 않습니다.

그 이유는 Git의 버전 관리 특성 때문입니다.
Git은 파일의 현재 상태뿐만 아니라 과거의 모든 기록(History)을 저장합니다. 여러분이 방금 파일을 삭제했다 하더라도, 이전 커밋 기록 어딘가에 그 대용량 파일이 남아있다면 Git은 그 기록까지 함께 Push 하려고 시도하기 때문에 여전히 용량 제한에 걸리게 됩니다.

따라서 해결책은 단순히 파일을 지우는 것이 아니라, Git의 과거 히스토리에서 해당 파일의 존재 자체를 완전히 도려내는 것입니다. 이때 가장 강력하고 권장되는 도구가 바로 git-filter-repo입니다.

---

2. 해결 도구: git-filter-repo란?

과거에는 git filter-branch나 BFG Repo-Cleaner를 많이 사용했지만, 현재 Git 공식 문서와 커뮤니티에서는 git-filter-repo 사용을 강력히 권장합니다. 이 도구는 Python 기반으로 작성되어 속도가 매우 빠르고, 복잡한 히스토리 재작성 작업을 안전하게 처리해 줍니다.

---

3. 단계별 해결 가이드

이제 본격적으로 꼬여버린 Git 히스토리를 수술해 보겠습니다.

Step 0. 사전 준비 (필수)

작업을 시작하기 전에 현재 작업 중인 내용을 모두 커밋하거나 스태시(Stash) 해두세요. 또한, 히스토리를 강제로 조작하는 작업이므로 혹시 모를 상황에 대비해 프로젝트 폴더를 통째로 다른 곳에 복사(백업)해 두는 것을 강력히 추천합니다.

git-filter-repo는 Python이 설치되어 있어야 합니다. 터미널에서 아래 명령어로 설치합니다.

pip install git-filter-repo
# 또는 mac 사용자라면
brew install git-filter-repo

Powershell 상에서의 명령 실행

Step 1. 대용량 파일 경로 확인

에러 메시지에서 문제가 되는 파일의 경로를 정확히 파악해야 합니다.
예를 들어 에러 메시지가 다음과 같다면:
remote: error: File assets/video/demo.mp4 is 133.58 MB...

삭제해야 할 파일의 경로는 assets/video/demo.mp4입니다.

Step 2. git-filter-repo 실행

이제 문제의 파일을 히스토리에서 제거합니다. 터미널에서 프로젝트 루트 경로로 이동한 뒤 아래 명령어를 입력하세요.

# 문법: git filter-repo --path [파일경로] --invert-paths

git filter-repo --path "assets/video/demo.mp4" --invert-paths

• --path "파일명": 특정 파일을 지정합니다.
• --invert-paths: 지정한 파일을 제외하고(Invert) 나머지만 남기겠다는 뜻입니다. 즉, 지정한 파일을 히스토리에서 삭제합니다.

주의: 만약 특정 폴더 전체를 지우고 싶다면 폴더 경로를 입력하면 됩니다.

명령 Aborting: Refusing to destructively overwrite repo history since this does not look like a fresh clone. (expected freshly packed repo) Please operate on a fresh clone instead. If you want to proceed anyway, use --force.실행 화면

 

만약 위와 같은 에러가 뜬다면, --force 옵션을 추가해 실행하면 됩니다.

Step 3. Remote 재설정 (중요)

git-filter-repo는 안전을 위해 작업 수행 후 기존의 remote (원격 저장소 연결) 정보를 자동으로 삭제합니다. 실수로 원격 저장소에 덮어쓰는 것을 방지하기 위함입니다.

따라서 원격 저장소를 다시 연결해 주어야 합니다.

# 원격 저장소 주소 확인 (GitHub 레포지토리 페이지에서 확인 가능)
git remote add origin https://github.com/사용자명/레포지토리명.git

Step 4. 강제 Push (Force Push)

이제 로컬 저장소의 히스토리는 깨끗해졌습니다. 하지만 원격 저장소(GitHub)의 히스토리와 로컬의 히스토리가 달라졌기 때문에, 일반적인 push는 거부됩니다.

변경된 히스토리를 원격 저장소에 덮어씌우기 위해 강제 푸시(Force Push)를 해야 합니다.

git push origin main --force
# 브랜치 이름이 master라면 git push origin master --force

이제 에러 없이 정상적으로 Push가 완료되는 것을 확인할 수 있습니다.

---

4. 대용량 파일을 꼭 사용해야 한다면? (Git LFS)

만약 100MB가 넘는 모델 파일이나 리소스를 반드시 Git으로 관리해야 한다면 어떻게 해야 할까요?
이때는 Git LFS (Large File Storage)를 사용해야 합니다.

Git LFS는 대용량 파일의 실제 데이터는 별도의 스토리지에 저장하고, Git에는 해당 파일의 포인터(링크)만 저장하여 용량을 획기적으로 줄여주는 기술입니다.

간단 사용법:

# 1. LFS 설치 (최초 1회)
git lfs install

# 2. 대용량 파일 추적 설정
git lfs track "*.psd" 
git lfs track "model.h5"

# 3. .gitattributes 파일 커밋
git add .gitattributes
git commit -m "Add LFS tracking"

이후에는 평소처럼 커밋하고 푸시하면 됩니다.

---

5. 결론

"Large files detected" 에러는 Git의 원리를 이해하지 못하면 해결하기 까다로운 문제입니다. 단순히 파일을 지우는 것이 아니라 git-filter-repo를 통해 히스토리 자체를 재작성해야 한다는 점을 꼭 기억해 주세요.

요약:

1. 100MB 초과 에러 발생 시 .gitignore만으로는 해결되지 않는다.
2. pip install git-filter-repo로 도구를 설치한다.
3. git filter-repo --path "파일경로" --invert-paths 명령어로 히스토리에서 파일을 제거한다.
4. git remote add origin ...으로 원격 저장소를 재연결한다.
5. git push --force로 반영한다.

이 포스팅이 여러분의 소중한 코드를 지키고, 쾌적한 개발 환경을 만드는 데 도움이 되기를 바랍니다.

---

Keywords: #Git #GitHub #git-filter-repo #GH001 #대용량파일에러 #Git히스토리삭제 #버전관리 #개발자팁 #GitLFS #프로그래밍