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 전용

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

프로젝트에 Git LFS 활성화

전제 조건: - 프로젝트에 적어도 개발자 역할이 있어야 합니다.

다음과 같이 수행하십시오:

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

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

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

알려진 제한 사항

  • Git LFS v1 원래 API는 지원되지 않습니다. 러프(LFS development) 초기에 폐기되었기 때문입니다.
  • SSH가 원격으로 설정되어 있을 때에도 Git LFS 객체는 여전히 HTTPS를 통해 전송됩니다.
  • Git LFS 요청은 모두 HTTPS 자격 증명을 요청하므로 좋은 Git 자격 증명 저장소를 권장합니다.
  • Git LFS는 항상 HTTPS를 가정하기 때문에 GitLab 서버가 HTTP 상에 있는 경우 URL을 수동으로 Git 구성에 추가해야 합니다.
  • 그룹 위키는 Git LFS를 지원하지 않습니다.

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

리포지토리에 LFS 객체를 추가하면 GitLab이 다음 작업을 수행합니다:

  1. LFS 객체를 생성합니다.
  2. LFS 객체를 리포지토리에 연결합니다.
  3. 프로젝트의 통계를 다시 계산하기 위한 작업을 큐에 넣습니다. 이에는 저장소 크기 및 LFS 객체 저장소가 포함됩니다. 귀하의 LFS 객체 저장소는 리포지토리와 관련된 모든 LFS 객체의 크기의 합입니다.

리포지토리가 포크될 때, 상위 프로젝트의 LFS 객체가 포크와 연관됩니다. 포크가 생성되는 경우 포크의 LFS 객체 저장소는 상위 프로젝트에서 사용한 저장소와 동일합니다. 새로운 LFS 객체가 포크에 추가되면 포크의 총 객체 저장소가 변경되지만 상위 프로젝트에는 변경되지 않습니다.

상위 프로젝트로부터 포크로 병합 요청을 생성하는 경우, 포크의 새 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를 통해 복제합니다. SSH URL을 사용하여 git clone 명령을 수행한 경우 HTTP 인증을 위해 GitLab 자격 증명을 입력해야 합니다. 

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

이미 리포지토리를 복제했고, 원격 리포지토리에 있는 최신 LFS 객체를 가져오고 싶은 경우, 예를 들어 main에서 origin 브랜치에 대해: 

git lfs fetch origin main

파일이 .gitignore에 나열되지 않았는지 확인하십시오. 그렇지 않으면 Git이 무시하고 원격 리포지토리에 푸시하지 않습니다.

기존 저장소를 Git LFS로 이관하기

기존 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 개발 문서에서 찾을 수 있습니다.

관련 주제