Git에서 대용량 파일 푸시 오류 해결하는 완벽 가이드
요즘 프로젝트의 규모가 커지면서 대용량 파일을 다루는 경우가 많아졌습니다. 저도 최근 프로젝트에서 이미지 에셋과 라이브러리 파일을 Git으로 관리하면서 푸시 오류를 경험했는데요. 특히 "RPC failed" 같은 오류 메시지를 보면 당황스러울 수 있습니다. 이번 글에서는 Git으로 대용량 파일을 푸시할 때 발생하는 문제와 이를 해결하는 방법을 공유해드리려 합니다.
Git의 대용량 파일 처리 한계
본격적인 문제 해결에 앞서, Git이 왜 대용량 파일 처리에 어려움을 겪는지 이해해볼게요. Git은 원래 소스 코드 같은 텍스트 파일 관리를 위해 설계되었습니다. 텍스트 파일은 일반적으로 크기가 작고, 변경 사항을 효율적으로 저장할 수 있습니다.
하지만 바이너리 파일이나 대용량 파일은 다릅니다:
- 작은 변경도 전체 파일을 다시 저장해야 함
- 네트워크 전송에 많은 시간 소요
- 저장소 크기가 빠르게 증가
- 클론 및 체크아웃 속도 저하
이러한 한계에도 불구하고, Git 설정을 조정하면 어느 정도 크기의 파일까지는 무리 없이 처리할 수 있습니다.
발생한 오류
Git으로 대용량 파일(약 25MB)을 푸시하려고 할 때 다음과 같은 오류가 발생했습니다:
Enumerating objects: 63, done.
Counting objects: 100% (63/63), done.
Delta compression using up to 16 threads
Compressing objects: 100% (42/42), done.
Writing objects: 100% (45/45), 25.45 MiB | 4.84 MiB/s, done.
Total 45 (delta 16), reused 0 (delta 0), pack-reused 0 (from 0)
error: RPC failed; curl 55 Failed sending data to the peer
send-pack: unexpected disconnect while reading sideband packet
fatal: the remote end hung up unexpectedly
Everything up-to-date
이 오류 메시지를 분석해보면:
- 25.45MB 크기의 데이터를 푸시하려고 했음
- 데이터 전송 중에 "RPC failed" 오류 발생
- curl 에러 코드 55는 데이터 전송 실패를 의미
- 원격 서버와의 연결이 예기치 않게 끊어짐
이는 주로 Git의 기본 설정이 대용량 파일 처리에 최적화되어 있지 않아서 발생하는 문제입니다.
해결 방법
여러 시도 끝에 다음 세 가지 Git 설정을 변경하여 문제를 해결할 수 있었습니다.
1. HTTP 버퍼 크기 증가
Git이 한 번에 처리할 수 있는 데이터 양을 늘려주는 설정입니다.
1git config --global http.postBuffer 524288000이 명령어는 HTTP 포스트 버퍼 크기를 약 500MB(524288000바이트)로 설정합니다. 기본값은 보통 1MB로, 대용량 파일을 처리하기에는 너무 작습니다.
2. 압축 비활성화
데이터 전송 시 압축 처리가 CPU에 부담을 줄 수 있으므로, 이를 비활성화하여 전송 과정에서 발생할 수 있는 문제를 방지합니다.
1git config --global core.compression 0압축 레벨을 0으로 설정하면 압축을 하지 않습니다. 기본값은 -1로, Git이 자동으로 압축 레벨을 결정합니다.
3. 네트워크 타임아웃 설정 변경
네트워크 연결이 느리거나 불안정할 때 타임아웃이 발생하는 것을 방지하기 위한 설정입니다.
1git config --global http.lowSpeedLimit 1000
2git config --global http.lowSpeedTime 300이 설정은 초당 1,000바이트 미만으로 300초(5분) 이상 지속될 경우에만 타임아웃이 발생하도록 합니다. 기본값은 각각 1KB/s와 5초로, 불안정한 연결에서는 너무 엄격한 설정입니다.
적용 결과
위의 설정을 모두 적용한 후 다시 푸시를 시도했더니 성공적으로 완료되었습니다.
Enumerating objects: 63, done.
Delta compression using up to 16 threads
Writing objects: 100% (45/45), 53.21 MiB | 123.56 MiB/s, done.
Total 45 (delta 16), reused 0 (delta 0), pack-reused 0 (from 0)
remote: . Processing 1 references
remote: Processed 1 references in total
To https://git.data-sketchers.com/datasketchers/d-sket-client-template-6.git
2a27696..da9461c main -> main
전송 속도도 이전(4.84 MiB/s)보다 훨씬 빨라진 123.56 MiB/s로 향상되었습니다!
추가 설정 및 대안
🟢 장점
- 설정 변경만으로 대용량 파일 푸시 문제를 해결할 수 있습니다
- 기존 워크플로우를 유지하면서 Git을 계속 사용할 수 있습니다
- 특별한 도구나 플러그인 설치 없이 적용 가능합니다
🟡 취향 요소
- 이러한 설정은 글로벌하게 적용할 수도 있고, 특정 저장소에만 적용할 수도 있습니다
- 버퍼 크기는 프로젝트 특성에 맞게 조정 가능합니다 (더 크거나 작게)
🔴 주의사항
- 이 방법은 중간 크기(~100MB)의 파일까지만 효과적입니다
- 매우 큰 파일(100MB+)이나 많은 대용량 파일을 다룰 때는 Git LFS 같은 전용 도구 사용을 고려해야 합니다
Git LFS 도입 고려하기
만약 프로젝트에서 지속적으로 대용량 파일을 다루어야 한다면, Git LFS(Large File Storage)를 도입하는 것이 좋습니다.
Git LFS는 대용량 파일을 효율적으로 관리할 수 있게 해주는 Git 확장 기능으로:
- 대용량 파일의 내용 대신 참조만 Git 저장소에 저장
- 실제 파일 내용은 별도의 LFS 서버에 저장
- 저장소 크기를 줄이고 클론 및 푸시 속도를 향상
- 필요할 때만 대용량 파일을 다운로드하는 지연 로딩 지원
Git LFS는 다음 명령으로 설치하고 설정할 수 있습니다:
1# Git LFS 설치 (Windows)
2git lfs install
3
4# 특정 파일 형식을 LFS로 관리하도록 설정
5git lfs track "*.psd"
6git lfs track "*.zip"
7git lfs track "*.mp4"
8
9# .gitattributes 파일도 커밋해야 함
10git add .gitattributes
11git commit -m "Configure Git LFS tracking"실제 적용 사례
제 경우는 디자인 에셋과 빌드된 라이브러리 파일들이 포함된 프로젝트였습니다. 단순히 설정만 변경했을 때는 50MB 정도까지는 잘 처리됐지만, 그 이상의 파일에서는 여전히 문제가 발생했습니다.
결국 Git LFS를 도입했고, 특히 자주 변경되지 않는 바이너리 파일(이미지, 동영상, ZIP 등)을 LFS로 관리하도록 설정했습니다. 이후로는 100MB가 넘는 파일도 문제없이 관리할 수 있게 되었습니다.
마무리
Git으로 대용량 파일을 푸시할 때 발생하는 오류는 설정 변경만으로도 해결할 수 있는 경우가 많습니다. 하지만 프로젝트의 성격과 파일 크기에 따라 Git LFS 같은 전용 도구 사용을 고려해보는 것이 좋습니다.
이러한 문제들은 Git을 처음 사용할 때는 당황스러울 수 있지만, 한 번 해결 방법을 알고 나면 쉽게 대처할 수 있습니다.
이 글이 Git으로 대용량 파일을 다루는 개발자분들에게 도움이 되었으면 좋겠습니다. 혹시 다른 해결 방법이나 팁이 있으시면 댓글로 공유해주세요! 🙌
다음에는 Git LFS 설정과 활용에 대한 더 자세한 내용을 다뤄보도록 하겠습니다.