Git Large File Storage (LFS)

대형 파일(예: 오디오, 비디오 및 그래픽 파일) 관리는 Git의 단점 중 하나였습니다. 일반적으로 권장되는 바에 따르면 성능을 유지하기 위해 Git 리포지터리의 크기가 1GB를 넘지 않아야 합니다.

Git LFS 클라이언트는 GitLab 서버와 HTTPS를 통해 통신합니다. 클라이언트 요청을 인가하기 위해 HTTP 기본 인증을 사용합니다. 요청이 인가되면 Git LFS 클라이언트는 대형 파일을 가져오거나 푸시할 위치에 대한 지시를 받습니다.

리포지터리보기에서 Git LFS로 추적된 파일은 파일 이름 옆에 LFS 뱃지로 표시됩니다:

Git LFS 추적 상태

Git LFS를 위한 GitLab 서버 구성

Tier: Free, Premium, Ultimate Offering: Self-managed, GitLab Dedicated

Self-managed GitLab 서버에 Git LFS를 설치하려면 GitLab Git Large File Storage (LFS) Administration을(를) 참조하십시오.

프로젝트에 대해 Git LFS 활성화

전제 조건:

  • 프로젝트에서 적어도 개발자 역할을 가져야 합니다.

이를 수행하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. Settings > General을(를) 선택합니다.
  3. 가시성, 프로젝트 기능, 권한 섹션을 확장합니다.
  4. Git Large File Storage (LFS) 토글을 켭니다.
  5. 변경 사항 저장을(를) 선택합니다.

로컬로 Git LFS 클라이언트 설치

운영 체제에 맞는 Git LFS 클라이언트를 설치하십시오. GitLab은 Git LFS 클라이언트의 1.0.1 버전 이상을 필요로 합니다.

알려진 제한 사항

  • Git LFS v1 원래 API는 개발 초기에 폐기되어 지원되지 않습니다.
  • 원격으로 SSH가 설정된 경우에도 Git LFS 객체는 여전히 HTTPS를 통해 전송됩니다.
  • 어떤 Git LFS 요청도 HTTPS 자격 증명을 요구하므로 좋은 Git 자격 증명 리포지터리를 권장합니다.
  • Git LFS는 항상 HTTPS를 가정하므로 GitLab 서버가 HTTP 상에 있는 경우 Git 구성에 URL을 매뉴얼으로 추가해야 합니다.
  • 그룹 위키는 Git LFS를 지원하지 않습니다.

LFS 객체가 리포지터리 크기에 미치는 영향

리포지터리에 LFS 객체를 추가하면 GitLab은 다음을 수행합니다:

  1. LFS 객체를 생성합니다.
  2. 해당 LFS 객체를 리포지터리와 연결합니다.
  3. 리포지터리의 크기 및 LFS 객체 리포지터리를 포함한 프로젝트 통계를 다시 계산하는 작업을 대기열에 넣습니다. LFS 객체 리포지터리는 리포지터리와 관련된 모든 LFS 객체의 크기의 합입니다.

리포지터리가 포크될 때는 상위 프로젝트의 LFS 객체가 포크와 관련됩니다. 포크가 생성되면 포크의 LFS 객체 리포지터리는 상위 프로젝트에서 사용된 리포지터리의 크기와 동일합니다. 포크에 새로운 LFS 객체가 추가되면 포크의 총 객체 리포지터리가 변경되지만 상위 프로젝트는 변경되지 않습니다.

포크에서 상위 프로젝트로 Merge Request을 생성하면 포크에서의 새로운 LFS 객체가 상위 프로젝트와 연관됩니다.

Git LFS 사용

Git LFS로 대형 파일을 Git 리포지터리에 체크인하는 작업 흐름을 살펴봅시다. 예를 들어, 매우 큰 파일을 업로드하고 Git 리포지터리에 체크인하려면 다음을 수행합니다: 

git clone git@gitlab.example.com:group/my-sample-project.git
cd my-sample-project
git lfs install                       # Git LFS 프로젝트를 초기화합니다
git lfs track "*.iso"                 # 대형 파일로 취급하려는 파일 확장자를 선택합니다

파일 확장자를 LFS 객체로 추적했으면 동일한 확장자를 가진 파일을 다시 추적하는 명령을 재입력하지 않고도 Git을 사용할 수 있습니다: 

cp ~/tmp/debian.iso ./                # 큰 파일을 현재 디렉터리로 복사합니다
git add .                             # 큰 파일을 프로젝트에 추가합니다
git commit -am "데비안 ISO 추가"     # 파일 메타 데이터를 커밋합니다
git push origin main                # git 레포 및 대형 파일을 GitLab 서버에 동기화합니다

반드시 .gitattributes가 Git에 의해 추적되는지 확인하십시오. 그렇지 않으면 Git LFS가 프로젝트를 복제하는 사람들에게 정상적으로 작동하지 않습니다: 

git add .gitattributes
git commit -am "LFS 추적을 캡처하기 위해 .gitattributes 추가"
git push origin main

리포지터리를 복제하는 방법은 이전과 동일합니다. Git은 자동으로 LFS로 추적된 파일을 감지하고 HTTP를 통해 복제합니다. git clone 명령을 SSH URL로 실행했다면 HTTP 인증을 위해 GitLab 자격 증명을 입력해야 합니다. 

git clone git@gitlab.example.com:group/my-sample-project.git

이미 리포지터리를 복제했고 원격 리포지터리의 최신 LFS 객체를 가져오려면, 예를 들어 origin 으로부터 브랜치를 위해: 

git lfs fetch origin main

파일이 .gitignore에 나열되지 않았는지 확인하여 Git에서 무시되지 않고 원격 리포지터리에 푸시되지 않도록 해야 합니다.

기존 리포지터리를 Git LFS로 마이그레이션

기존 Git 리포지터리를 Git LFS와 함께 마이그레이션하는 방법에 대한 문서를 참조하십시오.

LFS로부터 객체 제거

LFS로부터 객체를 제거하려면:

  1. git filter-repo를 사용하여 리포지터리에서 객체를 제거합니다.
  2. .gitattributes 파일에서 해당 객체에 대한 LFS 라인을 삭제하고 해당 변경 사항을 커밋합니다.

파일 잠금

파일 잠금에 대한 문서를 참조하십시오.

프로젝트 아카이브에 있는 LFS 객체

GitLab 13.5 이전에는 프로젝트 소스 다운로드는 실제 객체 대신 Git LFS 포인터를 포함했습니다. 예를 들어, LFS 포인터는 다음과 같습니다. 

version https://git-lfs.github.com/spec/v1
oid sha256:3ea5dd307f195f449f0e08234183b82e92c3d5f4cff11c2a6bb014f9e0de12aa
size 177735

GitLab 버전 13.5부터는 이러한 포인터가 업로드된 LFS 객체로 변환됩니다.

이 동작에 대한 기술적인 세부 정보는 LFS 개발 문서에서 찾을 수 있습니다.

관련 주제