Git Large File Storage (LFS)

Git Large File Storage (LFS)는 Git 리포지터리가 큰 바이너리 파일을 효율적으로 관리하는 데 도움을 줍니다. Git LFS를 사용하여 리포지터리에 파일을 추가할 때, GitLab에서는 다음을 수행합니다:

  1. 파일을 Git 리포지터리가 아닌 프로젝트의 구성된 객체 리포지터리에 배치합니다.
  2. 대형 파일 대신 Git 리포지터리에 포인터를 추가합니다. 이 작은 파일은 Git이 파일의 전체 버전을 찾을 위치를 알려줍니다.
  3. 프로젝트의 통계를 다시 계산하는 작업을 대기열에 넣어, 저장 크기 및 LFS 객체 리포지터리를 포함합니다. 여러분의 LFS 객체 리포지터리는 리포지터리와 관련된 모든 LFS 객체의 크기의 합입니다.

Git LFS로 관리되는 파일은 파일 이름 옆에 LFS 뱃지가 표시됩니다:

Git LFS 추적 상태

Git 리포지터리는 여전히 작아지므로 리포지터리 크기 제한을 준수하는 데 도움이 됩니다. 자세한 내용은 리포지터리 크기 제한을 참조하세요. Self-Managed형 및 GitLab.com.

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

Git LFS가 포크와 함께 작동하는 방법 이해하기

리포지터리를 포크할 때, 포크에는 생성 시점의 상류 리포지터리의 존재했던 LFS 객체가 포함됩니다. 포크에 새로운 LFS 객체를 추가하는 경우, 해당 객체는 상류 리포지터리가 아닌 포크에 속합니다. 전체 객체 리포지터리 크기는 포크에만 증가합니다.

포크에서 상류 프로젝트로 Merge Request을 생성하고 Merge Request이 새로운 Git LFS 객체를 포함하는 경우, GitLab은 Merge 후의 신규 LFS 객체를 상류 프로젝트와 연관시킵니다.

알려진 제한 사항

  • Git LFS 원본 v1 API는 지원되지 않습니다.
  • Git이 리포지터리와 SSH를 통해 통신하더라도, Git LFS 객체는 여전히 HTTPS를 사용합니다.
  • Git LFS 요청은 HTTPS 자격 증명을 사용하므로:
    • 좋은 Git 자격 증명 리포지터리를 사용해야 합니다.
    • GitLab 서버가 HTTP를 사용하는 경우, Git 구성에 URL을 매뉴얼으로 추가해야 합니다.
  • 그룹 위키는 Git LFS를 지원하지 않습니다.

Git LFS로 파일 추가

필수 요건:

  • 사용 중인 운영 체제에 맞는 버전의 Git LFS를 위한 CLI 확장 프로그램을 다운로드하고 설치했어야 합니다.
  • 프로젝트의 루트 디렉터리에서 git lfs install을 실행하여 Git LFS 프리-푸시 후크를 설치했어야 합니다.

큰 파일을 Git 리포지터리에 추가하고 Git LFS로 추적하는 방법:

  1. 특정 유형의 모든 파일을 Git LFS로 추적하려면 단일 파일이 아닌 다음 명령을 실행하여 iso를 원하는 파일 유형으로 대체합니다: 

    git lfs track "*.iso"

    이 명령은 모든 ISO 파일을 Git LFS로 처리하는 지침이 포함된 .gitattributes 파일을 생성합니다.

  2. 이 유형의 파일(.iso)을 리포지터리에 추가합니다.

  3. Git이 .gitattributes 파일과 .iso 파일의 변경 사항을 추적하도록 지시합니다.: 

    git add .
  4. 두 파일을 추가했는지 확인하려면 git status를 실행하세요. .gitattributes 파일이 커밋에 포함되지 않은 경우, 리포지터리를 복제하는 사용자는 필요한 파일을 얻지 못합니다.

  5. 로컬 리포지터리의 두 파일을 커밋합니다.: 

    git commit -am "ISO 파일 및 .gitattributes 추가"

  6. 변경 사항을 원격 리포지터리에 다시 푸시하면서 단 main을 여러분의 브랜치 이름으로 대체합니다.: 

    git push origin main

    변경하는 파일이 .gitignore 파일에 나열되어 있지 않은지 확인합니다. 만일 이 파일(또는 이 유형의 모든 파일)이 .gitignore 파일에 포함되어 있다면, Git은 변경 사항을 로컬로 커밋하지만 원격 리포지터리에 푸시하지 않습니다.

  7. Merge Request을 생성합니다.

Git LFS로 파일 추적 중지

필수 요건:

  • 사용 중인 운영 체제에 맞는 버전의 Git LFS를 위한 CLI 확장 프로그램을 다운로드하고 설치했어야 합니다.
  • 프로젝트의 루트 디렉터리에서 git lfs install을 실행하여 Git LFS 프리-푸시 후크를 설치했어야 합니다.

Git LFS에서 단일 파일 추적 중지:

  1. git lfs untrack 명령을 실행하고 파일 경로를 제공합니다.: 

    git lfs untrack doc/example.iso

  2. 변경 사항을 푸시하고 Merge Request을 생성한 뒤, Merge Request을 Merge합니다.

Git LFS가 추적하는 특정 유형의 모든 파일 추적 중지:

  1. git lfs untrack 명령을 실행하고 추적을 중지할 파일 유형을 제공합니다.: 

    git lfs untrack "*.iso"

  2. 변경 사항을 푸시하고 Merge Request을 생성한 뒤, Merge Request을 Merge합니다.

서버에서 Git LFS 구성

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

Git LFS는 Self-Managed형 인스턴스 및 GitLab.com 모두에서 기본적으로 활성화되어 있습니다. 원격 객체 리포지터리 설정과 같이 Git LFS를 구성하려면, GitLab Git Large File Storage (LFS) Administration을 참조하세요.

프로젝트에 대해 Git LFS를 활성화 또는 비활성화하기

Git LFS는 Self-Managed형 인스턴스 및 GitLab.com 모두에서 기본적으로 활성화되어 있습니다.

필수 요건:

  • 프로젝트에서 적어도 Developer 역할이 있어야 합니다.

프로젝트 수준에서 Git LFS를 활성화하거나 비활성화하려면:

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

Git LFS를 사용하는 리포지터리 복제하기

Git LFS를 사용하는 리포지터리를 복제하면 Git이 LFS로 추적된 파일을 감지하고 HTTPS를 통해 그 파일들을 복제합니다. SSH URL로 user@hostname.com:group/project.git와 같이 git clone을 실행하면 HTTPS 인증을 위해 GitLab 자격 증명을 다시 입력해야 합니다.

LFS 객체의 로컬 복제 업데이트하기

이미 Git LFS를 사용하는 리포지터리를 복제한 경우, 상류 리포지터리로부터 새로운 LFS 객체를 가져오려면 다음을 실행합니다: 

git lfs fetch origin main

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

기존 Git 리포지터리를 Git LFS로 마이그레이션하는 방법에 대한 git-lfs-migrate 문서를 참조하세요.

관련 주제

문제 해결

대형 파일 제거 후 리포지터리 크기 축소

리포지터리의 총 크기를 줄이기 위해 리포지터리 기록에서 대형 파일을 제거해야 할 경우 리포지터리 크기 축소를 참조하세요.