Git Large File Storage (LFS)

Git Large File Storage (LFS)는 Git 저장소가 대용량 이진 파일을 효율적으로 관리할 수 있도록 돕는 오픈 소스 Git 확장 기능입니다. Git은 텍스트 파일의 변경을 추적하는 방식과는 다르게 오디오, 비디오 또는 이미지 파일과 같은 이진 파일의 변경을 추적할 수 없습니다. 텍스트 기반 파일은 일반 텍스트 차이를 생성할 수 있지만, 이진 파일의 변경 사항은 Git이 저장소 내에서 파일을 완전히 교체해야 합니다. 대용량 파일에 대한 반복적인 변경은 저장소 크기를 증가시킵니다. 시간이 지남에 따라 크기가 증가하면 clone, fetch, 또는 pull과 같은 정규 Git 작업이 느려질 수 있습니다.

Git LFS를 사용하면 대용량 이진 파일을 Git 저장소 외부에 저장하고, Git이 관리하는 작은 텍스트 기반 포인터만 남깁니다. Git LFS를 사용하여 파일을 저장소에 추가할 때 GitLab은 다음 작업을 수행합니다.

  1. 파일을 프로젝트의 구성된 객체 저장소에 추가합니다. Git 저장소가 아닙니다.

  2. 대용량 파일 대신 Git 저장소에 포인터를 추가합니다. 포인터에는 다음과 같은 파일에 대한 정보가 포함됩니다. 

    version https://git-lfs.github.com/spec/v1
oid sha256:lpca0iva5kpz9wva5rgsqsicxrxrkbjr0bh4sy6rz08g2c4tyc441rto5j5bctit
size 804
    • Version - 사용 중인 Git LFS 사양의 버전
    • OID - 사용된 해싱 방법과 고유한 객체 식별자로, 형식은 {해시-방법}:{해시}
    • Size - 파일 크기 (바이트 단위)
  3. 프로젝트의 통계를 다시 계산하는 작업을 대기열에 추가하여 저장소 크기 및 LFS 객체 저장소를 포함한 프로젝트의 통계를 다시 계산합니다. LFS 객체 저장소는 저장소와 관련된 모든 LFS 객체의 크기의 합입니다.

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

Git LFS 추적 상태

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

Git 저장소는 여전히 작아져서 저장소 크기 제한을 준수하는 것을 도와줍니다. 자세한 내용은 저장소 크기 제한에 대해 자체 관리 및 GitLab.com을 참조하세요.

포크 작업과 Git LFS 작업 방법 이해

저장소를 포크하면 포크에는 포크한 시점에서 기존의 LFS 객체를 포함한 상위 저장소의 LFS 객체가 포함됩니다. 포크에 새 LFS 객체를 추가하면 해당 객체는 본인의 포크에만 속하고 상위 저장소에는 속하지 않습니다. 전체 객체 저장소는 해당 포크를 위해 증가합니다.

포크한 저장소에서 상위 프로젝트로의 병합 요청을 생성하고 해당 병합 요청에 새 Git LFS 객체가 포함되어 있으면 병합 후에 GitLab은 새 LFS 객체를 상위 프로젝트와 연결시킵니다.

프로젝트용 Git LFS 구성

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

GitLab은 자체 관리 인스턴스 및 GitLab.com 모두에 대해 Git LFS를 기본적으로 활성화합니다. 서버 설정 및 프로젝트별 설정 둘 다 제공됩니다.

  • 원격 객체 저장소 설정과 같은 인스턴스용 Git LFS를 구성하려면 GitLab Git Large File Storage (LFS) Administration을 참조하세요.

  • 특정 프로젝트용 Git LFS를 구성하려면:

    1. 저장소의 로컬 복사본의 루트 디렉토리에서 git lfs install를 실행합니다. 이 명령은 다음을 추가합니다:
      • 저장소에 미리 푸시하는 Git 후크
      • .gitattributes 파일을 사용하여 개별 파일 및 파일 유형에 대한 처리를 추적합니다.
    2. Git LFS로 추적하려는 파일 및 파일 유형을 추가합니다.

Git LFS로 파일 추가

전제 조건:

대용량 파일을 저장소에 추가하고 즉시 Git LFS로 추적하려면 다음을 수행합니다:

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

    git lfs track "*.iso"

    이 명령은 모든 ISO 파일을 Git LFS로 처리하는 .gitattributes 파일을 만듭니다. .gitattributes 파일의 행은 다음과 같이 보입니다: 

    *.iso filter=lfs -text
  2. 해당 유형의 파일(.iso)을 저장소에 추가합니다.

  3. 변경 사항을 .gitattributes 파일과 .iso 파일 모두 추적하도록 Git에 지시합니다. 

    git add .
  4. 두 파일을 모두 커밋했는지 확인하기 위해 git status를 실행합니다. 만약 .gitattributes 파일이 커밋에 포함되어 있지 않으면, 저장소를 복제하는 사용자는 필요한 파일을 받지 못합니다.

  5. 로컬 저장소의 변경 사항을 커밋합니다: 

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

  6. main을 자신의 브랜치 이름으로 바꾸어 저장소에 변경 사항을 푸시합니다. 

    git push origin main

    변경 사항이 있는 파일이 .gitignore 파일에 나열되어 있지 않은지 확인하세요. 해당 파일(또는 파일 유형)이 .gitignore 파일에 있는 경우 Git은 로컬로 변경을 커밋하지만 상위 저장소로 푸시하지 않습니다.

  7. 병합 요청을 생성합니다.

Git LFS로 파일 유형 추가

새로운 파일 유형을 Git LFS 추적에 추가하면 이미 존재하는 파일 유형은 _변환되지 않습니다. Git LFS 추적을 시작한 이후에 해당 유형의 파일만 Git LFS에 추가됩니다. 해당 유형의 기존 파일을 Git LFS를 사용하도록 변환하려면 git lfs migrate를 사용합니다.

전제 조건:

Git LFS에서 파일 유형을 추적하려면 다음을 수행합니다:

  1. 프로젝트의 .gitignore 파일에 해당 파일 유형이 나열되어 있지 않은지 확인합니다. 파일 유형이 .gitignore 파일에 있는 경우 변경 사항을 커밋해도 상위 저장소로 푸시하지 않습니다.

  2. 각 파일 유형에 대해 추적할지를 결정합니다. 각 파일 유형에 대해 다음 명령을 실행하고 iso를 원하는 파일 유형으로 대체하세요. 

    git lfs track "*.iso"

  3. .gitattributes 파일의 변경 사항을 커밋하도록 Git에 지시합니다. 해당된 파일을 로컬 저장소에 커밋합니다. filetype을 자신의 브랜치 이름으로 바꾸어 변경 사항을 푸시합니다. 

    git add .
git commit -am "파일 유형 .iso에 Git LFS 사용"
git push origin filetype

Git LFS로 파일 추적 중단하기

Git LFS로 파일 추적을 중단하면 해당 파일은 여전히 저장소의 히스토리에 남아 있기 때문에 디스크에 남습니다. 그 이유에 대해 이해하려면 저장소 히스토리에서 Git LFS 파일 삭제하기를 참조하십시오.

전제 조건:

  • 해당 운영 체제용 CLI extension for Git LFS의 적절한 버전을 다운로드하고 설치했습니다.
  • 저장소의 루트 디렉터리에서 git lfs install을 실행하여 Git LFS pre-push 훅을 설치했습니다.

Git LFS로 파일 추적 중단하기:

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

    git lfs untrack doc/example.iso

  2. touch 명령을 사용하여 해당 파일을 표준 파일로 변환합니다: 

    touch doc/example.iso

  3. 파일의 변경 사항을 추적하도록 Git에 알립니다: 

    git add .
  4. 변경 사항을 커밋하고 푸시합니다.
  5. 병합 요청을 생성하고 리뷰를 요청합니다.
  6. 필요한 승인을 받은 후, 해당 병합 요청을 대상 브랜치에 병합합니다.

Git LFS에서 추적 중인 (example.iso) 객체를 삭제하지만 git lfs untrack 명령을 사용하지 않으면, example.iso가 git status에서 modified로 표시됩니다.

특정 유형의 모든 파일 추적 중단하기

전제 조건:

  • 해당 운영 체제용 CLI extension for Git LFS의 적절한 버전을 다운로드하고 설치했습니다.
  • 저장소의 루트 디렉터리에서 git lfs install을 실행하여 Git LFS pre-push 훅을 설치했습니다.

Git LFS에서 특정 유형의 모든 파일 추적 중단하기:

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

    git lfs untrack "*.iso"

  2. touch 명령을 사용하여 해당 파일을 표준 파일로 다시 변환합니다: 

    touch *.iso

  3. 파일의 변경 사항을 추적하도록 Git에 알립니다: 

    git add .
  4. 변경 사항을 커밋하고 푸시합니다.
  5. 병합 요청을 생성하고 리뷰를 요청합니다.
  6. 필요한 승인을 받은 후, 해당 병합 요청을 대상 브랜치에 병합합니다.

프로젝트에서 Git LFS 사용 설정 또는 해제하기

Git LFS는 자체 관리 인스턴스와 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 자격 증명을 다시 입력해야 합니다.

기본적으로 Git LFS 작업은 HTTPS를 통해 발생하지만 Git이 SSH를 통해 저장소와 통신할 때도 HTTPS를 통해 발생합니다. GitLab 17.2에서는 LFS에 대한 순수 SSH 지원이 소개되었습니다. 이 기능을 사용하도록 설정하는 방법에 대한 정보는 순수 SSH 전송 프로토콜을 참조하십시오.

이미 복제한 저장소에 대해 새로운 LFS 객체를 가져오려면 다음 명령을 실행하십시오: 

git lfs fetch origin main

기존 저장소를 Git LFS로 마이그레이션하기

기존 Git 저장소를 Git LFS와 함께 마이그레이션하는 방법에 대한 git-lfs-migrate 문서를 참조하십시오.

저장소 히스토리에서 Git LFS 파일 삭제하기

Git LFS로 추적되는 파일을 삭제하는 것과 파일 추적을 중단하는 것의 차이점을 이해하는 것이 중요합니다:

  • 추적 중단: 파일은 디스크에 남아 있고 저장소 히스토리에도 남아 있습니다. 사용자가 이전 브랜치 또는 태그를 체크아웃하면 해당 파일의 LFS 버전이 여전히 필요합니다.
  • 삭제: 파일이 제거되지만 저장소 히스토리에는 남아 있습니다.

Git LFS로 추적되는 파일을 삭제하려면 파일 제거를 참조하십시오.

과거와 현재의 파일 히스토리를 완전히 삭제하려면, 커밋에서 민감한 정보 삭제를 참조하십시오.

경고: 파일 히스토리를 완전히 삭제하려면 Git 히스토리를 다시 작성해야 합니다. 이 작업은 파괴적이며 되돌릴 수 없습니다.

큰 파일을 제거한 후 저장소 크기 줄이기

저장소의 히스토리에서 큰 파일을 제거하여 저장소의 총 크기를 줄이려면 저장소 크기 줄이기를 참조하십시오.

관련 주제