스크린샷 자동화가 Git Repo를 부풀리고 있습니다

Source: Dev.to

문제: 스크린샷이 레포를 부풀리는 경우

몇 주 전에 문서 스크린샷을 자동화했습니다. 매주 한 번의 명령으로 30개 이상의 PNG가 재생성됩니다. 이제 수동으로 스크린샷을 찍을 필요가 없었죠. 상황은 좋았지만 레포 크기를 확인했을 때 문제가 드러났습니다.

• 레포 크기: 문서 프로젝트 기준 412 MB.
• 이유: Git은 바이너리 파일을 전체 복사본으로 저장합니다. 스크린샷이 한 픽셀만 바뀌어도 Git은 파일 전체를 다시 저장합니다.
• 영향: 매주 30개의 스크린샷이 업데이트 → 연간 약 156 MB의 히스토리가 쌓임.
• 결과: 새 기여자가 레포를 클론할 때 대기 시간이 길어지고, CI 파이프라인이 수백 메가바이트에 달하는 오래된 PNG를 다운로드하게 됩니다(사실상 다시 볼 일은 없습니다).

해결책: Git LFS 사용

Git LFS는 이미지 파일을 작은 포인터 파일(≈130 바이트)로 대체합니다. 실제 이미지는 별도 서버에 보관되지만, 체크아웃은 정상적으로 이루어져 차이를 느끼지 못합니다.

일회성 설정

git lfs install
git lfs track "heroshots/*.png"
git add .gitattributes
git commit -m "configure Git LFS"

일반적인 Git 워크플로(git add, git commit, git push)는 그대로 유지됩니다. LFS가 배경에서 라우팅을 담당합니다.

기존 이미지 마이그레이션

git lfs migrate import --include="heroshots/*.png"
git push --force-with-lease

위에서 언급한 레포는 마이그레이션 후 412 MB에서 28 MB로 축소되었습니다.

CI 연동 (GitHub Actions)

GitHub Actions에서 스크린샷 업데이트를 실행한다면, 체크아웃 단계에서 LFS를 활성화합니다:

- uses: actions/checkout@v4
  with:
    lfs: true

이 옵션을 빼면 CI 작업은 포인터 파일(130 바이트 텍스트 파일)만 받게 되어 스크린샷 비교 단계가 실패합니다.

Git LFS 사용 시점

• LFS를 건너뛰세요 스크린샷이 몇 개에 불과하고 거의 변경되지 않을 경우. 일반 Git으로 충분합니다.
• LFS를 사용하세요 자동화된 스크린샷 워크플로가 있는 경우:
  • 주당 30개 이상의 이미지가 업데이트
  • 여러 명의 기여자 팀
  • 많은 클론을 유발하는 오픈소스 프로젝트

간단한 판단 기준

추가 자료

자세한 내용은 heroshot 문서를 참고하세요.