NODELOG
구독하기
홈/엔지니어/Git / CI·CD/Git LFS 완전 가이드 — 대용량 파일 버전 관…
Git / CI·CD중급linuxmacoswindowsgitgit-lfslarge-files

Git LFS 완전 가이드 — 대용량 파일 버전 관리

Git Large File Storage(LFS)의 동작 원리와 설치, git lfs track으로 추적 패턴 지정, .gitattributes 관리, 기존 히스토리 마이그레이션, 부분 체크아웃, 저장소 용량 관리까지 대용량 파일을 Git으로 다루는 방법을 정리합니다.

SESecuThive0 조회

Git LFS 란?

Git은 텍스트 소스코드의 변경 이력을 다루는 데 최적화되어 있습니다. 하지만 이미지·동영상·디자인 원본·데이터셋·바이너리 같은 대용량 파일을 그대로 커밋하면 모든 버전이 .git 히스토리에 통째로 쌓여 저장소가 수 GB로 불어나고, clone·fetch가 극도로 느려집니다. 한 번 커밋한 큰 파일은 나중에 지워도 히스토리에 영원히 남습니다.

Git LFS(Large File Storage) 는 이 문제를 해결하는 확장 기능입니다. 큰 파일의 실제 내용은 별도 LFS 스토리지에 두고, Git 저장소에는 그 파일을 가리키는 포인터(pointer) 파일(수십 바이트의 텍스트)만 커밋합니다.

CODE
version https://git-lfs.github.com/spec/v1
oid sha256:4d7a214614ab2935c943f9e0ff69d22eadbb8f32b1258daaa5e2ca24d17e2393
size 12345678

체크아웃 시 이 포인터를 읽어 실제 파일을 LFS 서버에서 내려받습니다. 덕분에 히스토리는 가벼워지고 필요한 버전만 받게 됩니다.

설치

Bash
# macOS
brew install git-lfs

# Debian / Ubuntu
sudo apt install git-lfs

# RHEL / Rocky
sudo dnf install git-lfs

# 설치 확인
git lfs version

설치 후 사용자 계정에 한 번 초기화합니다(머신당 1회).

Bash
git lfs install

이 명령은 전역 Git 설정에 LFS용 filter/smudge/clean 후크를 등록합니다.

추적할 파일 지정 — git lfs track

저장소 안에서 어떤 파일을 LFS로 다룰지 패턴으로 지정합니다.

Bash
# 확장자 기준
git lfs track "*.psd"
git lfs track "*.mp4"
git lfs track "*.zip"

# 특정 디렉터리 전체
git lfs track "assets/models/**"

# 현재 추적 규칙 확인
git lfs track

이 명령은 저장소 루트에 .gitattributes 파일을 생성·수정합니다.

CODE
*.psd  filter=lfs diff=lfs merge=lfs -text
*.mp4  filter=lfs diff=lfs merge=lfs -text
*.zip  filter=lfs diff=lfs merge=lfs -text

.gitattributes는 반드시 커밋해야 합니다. 이 파일이 없으면 협업자나 CI는 해당 파일을 일반 파일로 처리해 LFS가 동작하지 않습니다.

Bash
git add .gitattributes
git commit -m "chore: track binary assets with Git LFS"

이후 *.psd 같은 파일을 추가·커밋·푸시하면 자동으로 LFS로 처리됩니다.

Bash
git add design/cover.psd
git commit -m "feat: add cover artwork"
git push origin main

추적 상태 확인

Bash
# LFS로 관리되는 파일 목록
git lfs ls-files

# 출력 예
# 4d7a214614 * design/cover.psd
# a91f0c8e2b - assets/intro.mp4

# 저장소·LFS 환경 진단
git lfs env

# 특정 파일이 포인터인지 실제 파일인지 확인
git lfs pointer --file=design/cover.psd

ls-files에서 *는 작업 트리에 실제 파일이 내려와 있음을, -는 포인터만 있음을 의미합니다.

기존 히스토리 마이그레이션

이미 큰 파일을 일반 방식으로 커밋해 버린 저장소는 git lfs track만으로는 과거 커밋이 정리되지 않습니다. git lfs migrate로 히스토리를 다시 씁니다.

Bash
# 현재 브랜치 히스토리에서 *.psd, *.zip 을 LFS로 변환
git lfs migrate import --include="*.psd,*.zip"

# 모든 브랜치/태그 대상
git lfs migrate import --include="*.psd" --everything

migrate import는 커밋 해시를 모두 바꿉니다(history rewrite). 공유 중인 브랜치라면 협업자와 합의 후 진행하고, 푸시는 git push --force-with-lease를 사용하세요. 진행 전 백업은 필수입니다.

반대로 LFS를 걷어내고 일반 파일로 되돌리려면 git lfs migrate export --include="*.psd"를 사용합니다.

부분 체크아웃 — 대역폭 절약

대용량 저장소에서 LFS 파일을 매번 다 받지 않도록 제어할 수 있습니다.

Bash
# LFS 파일은 받지 않고 포인터만 clone (빠름)
GIT_LFS_SKIP_SMUDGE=1 git clone <repo-url>

# 나중에 필요한 것만 받기
git lfs pull --include="design/*.psd"

# 특정 패턴은 항상 제외
git config lfs.fetchexclude "assets/raw/**"

# 최근 커밋의 파일만 받기 (오래된 버전 스킵)
git config lfs.fetchrecentcommitsdays 7

LFS vs 일반 Git 처리 비교

항목일반 Git 커밋Git LFS
저장소에 들어가는 것파일 전체(모든 버전)포인터 텍스트만
clone 속도누적될수록 느려짐필요한 버전만 받아 빠름
큰 파일 diff거의 불가능포인터 비교(메타데이터)
히스토리 용량계속 증가가볍게 유지
적합 대상텍스트 소스이미지·영상·바이너리·데이터셋

저장소 용량과 정리

LFS 객체는 로컬 .git/lfs/objects에 캐시됩니다. 오래된 객체는 정리할 수 있습니다.

Bash
# 원격에 이미 있고 현재 안 쓰는 로컬 LFS 객체 제거
git lfs prune

# 어떤 게 지워질지 미리보기
git lfs prune --dry-run

# 모든 LFS 객체를 미리 받아두기
git lfs fetch --all

GitHub·GitLab 등 호스팅 서비스는 LFS 저장 용량과 대역폭에 별도 할당량이 있습니다(예: GitHub 무료 1GB 저장 / 월 1GB 대역폭). 대용량 데이터셋은 비용을 사전에 확인하세요.

트러블슈팅

증상원인 / 해결
clone 후 파일이 포인터 텍스트로 보임git lfs install 미실행 → 실행 후 git lfs pull
협업자에게 LFS가 안 먹힘.gitattributes 미커밋 → 커밋 후 공유
push 시 batch response: 403LFS 권한/할당량 문제. 토큰·용량 확인
큰 파일이 이미 일반 커밋됨git lfs migrate import로 변환
smudge filter lfs failed네트워크/인증 문제. GIT_LFS_SKIP_SMUDGE=1로 우회 후 git lfs pull

.gitattributes 베스트 프랙티스

CODE
# 미디어
*.psd   filter=lfs diff=lfs merge=lfs -text
*.ai    filter=lfs diff=lfs merge=lfs -text
*.mp4   filter=lfs diff=lfs merge=lfs -text
*.mov   filter=lfs diff=lfs merge=lfs -text

# 아카이브 / 모델
*.zip       filter=lfs diff=lfs merge=lfs -text
*.tar.gz    filter=lfs diff=lfs merge=lfs -text
*.onnx      filter=lfs diff=lfs merge=lfs -text
*.bin       filter=lfs diff=lfs merge=lfs -text

-text 속성은 해당 파일을 바이너리로 취급해 줄바꿈 변환(CRLF↔LF)을 막습니다. LFS 대상에는 항상 붙이는 것이 안전합니다.

정리

작업명령
머신 초기화(1회)git lfs install
추적 패턴 지정git lfs track "*.psd"
추적 파일 목록git lfs ls-files
기존 히스토리 변환git lfs migrate import --include="*.zip"
포인터만 cloneGIT_LFS_SKIP_SMUDGE=1 git clone
필요한 것만 받기git lfs pull --include="..."
로컬 캐시 정리git lfs prune

Git LFS는 텍스트에 최적화된 Git의 약점을 메워, 대용량 파일을 가벼운 포인터로 다루게 해 줍니다. 핵심은 .gitattributes를 반드시 커밋하고, 기존 큰 파일은 migrate로 정리하며, 호스팅 할당량을 관리하는 것입니다.

#git#git-lfs#large-files#version-control
편집 안내 · Editorial Note

이 가이드는 AI 도구를 활용해 초안을 구성하고 사람이 명령어·문맥을 검토해 발행했습니다. 운영체제와 도구 버전에 따라 결과가 달라질 수 있으므로 적용 전 공식 문서를 함께 확인하세요. 오류를 발견하시면 이메일로 제보해 주세요.

관련 공식 문서Git 공식 문서 ↗
운영·검토 방식 →편집 정책 →

질문 & 답변 (Q&A)

이 가이드에 대해 궁금한 점을 질문해보세요. 확인 후 답변드립니다.

이 가이드와 연관된 블로그 글전체 글 →
개발

백엔드 아키텍처 설계 가이드: FastAPI vs Spring Boot vs Django, 상황별 최적 프레임워크 선택법

어떤 백엔드 프레임워크를 선택해야 할지 고민이신가요? FastAPI, Spring Boot, Django의 핵심 개념부터 실제 프로젝트의 요구사항에 따른 장단점 비교표, 그리고 아키텍처적 의사결정 가이드라인까지 완벽하게 정리했습니다.

개발

프로젝트 규모별 CI/CD 툴 선택 가이드: GitHub Actions vs GitLab vs Jenkins 완벽 비교

어떤 CI/CD 툴을 선택해야 할지 막막하신가요? 이 가이드는 단순 기능 나열을 넘어, 프로젝트 규모(소규모/스타트업/엔터프라이즈)와 요구사항에 맞춰 최적의 자동화 워크플로우를 설계하는 방법을 제시합니다.

개발

테스트 전략 가이드: 주니어/미드 개발자를 위한 테스트 유형별 적용 로드맵

테스트가 막막하게 느껴지시나요? 이 가이드는 테스트 피라미드를 기반으로, 어떤 테스트를 얼마나 작성해야 하는지 명확한 로드맵을 제시합니다. 테스트 커버리지 목표 설정부터 자동화 도입 단계까지 실무에 바로 적용 가능한 전략을 얻어 가세요.