Git LFS를 사용할 때 다음과 같은 문제가 발생할 수 있습니다.

• Git LFS 구버전 v1 API는 지원되지 않습니다.

• Git LFS 요청은 HTTPS 자격 증명을 사용하므로, Git 자격 증명 저장소를 사용해야 합니다.

• 그룹 위키는 Git LFS를 지원하지 않습니다.

오류: 리포지터리 또는 오브젝트를 찾을 수 없음#

이 오류는 다음과 같은 몇 가지 이유로 발생할 수 있습니다.

• 특정 LFS 오브젝트에 접근할 권한이 없습니다. 프로젝트에 푸시하거나 프로젝트에서 페치할 권한이 있는지 확인하세요.

• 프로젝트가 LFS 오브젝트에 접근할 수 없습니다. 푸시(또는 페치)하려는 LFS 오브젝트가 더 이상 프로젝트에서 사용할 수 없습니다. 대부분의 경우 오브젝트가 서버에서 제거된 것입니다.

• 로컬 Git 리포지터리가 더 이상 사용되지 않는 Git LFS API 버전을 사용하고 있습니다. 로컬 Git LFS 복사본을 업데이트하고 다시 시도하세요.

<url>에 대한 잘못된 상태: 501#

Git LFS는 실패를 로그 파일에 기록합니다. 이 로그 파일을 보려면:

터미널 창에서 프로젝트 디렉터리로 이동합니다.

다음 명령을 실행하여 최근 로그 파일을 확인합니다.

git lfs logs last

다음 문제가 501 오류를 유발할 수 있습니다.

• 프로젝트 설정에서 Git LFS가 활성화되어 있지 않습니다. 프로젝트 설정을 확인하고 Git LFS를 활성화하세요.

• GitLab 서버에서 Git LFS 지원이 활성화되어 있지 않습니다. GitLab 관리자에게 서버에서 Git LFS가 활성화되지 않은 이유를 문의하세요. Git LFS 지원을 활성화하는 방법은 LFS 관리 문서를 참조하세요.

• Git LFS 클라이언트 버전이 GitLab 서버에서 지원되지 않습니다. 다음을 수행하세요.

git lfs version 명령으로 Git LFS 버전을 확인합니다.

• git lfs -l 명령으로 더 이상 사용되지 않는 API 관련 흔적이 있는지 프로젝트의 Git 구성을 확인합니다. 구성에 batch = false가 설정되어 있으면 해당 줄을 제거한 후 Git LFS 클라이언트를 업데이트하세요. GitLab은 버전 1.0.1 이상만 지원합니다.

오브젝트 푸시 시 항상 자격 증명이 요구됨#

Git LFS는 모든 푸시 시 모든 오브젝트에 대해 HTTP Basic 인증으로 사용자를 인증하므로, 사용자 HTTPS 자격 증명이 필요합니다. 기본적으로 Git은 사용하는 각 리포지터리의 자격 증명을 기억하는 기능을 지원합니다. 자세한 내용은 공식 Git 문서를 참조하세요.

예를 들어, 오브젝트를 푸시할 것으로 예상되는 기간 동안 비밀번호를 기억하도록 Git에 지시할 수 있습니다. 이 예시는 자격 증명을 한 시간(3600초) 동안 기억하며, 한 시간 후에는 다시 인증해야 합니다.

git config --global credential.helper 'cache --timeout=3600'

자격 증명을 저장하고 암호화하려면 다음을 참조하세요.

• MacOS: osxkeychain을 사용합니다.

• Windows: wincred 또는 Microsoft Git Credential Manager for Windows를 사용합니다.

사용자 자격 증명 저장에 대한 자세한 내용은 Git 자격 증명 저장소 문서를 참조하세요.

푸시 시 LFS 오브젝트 누락#

GitLab은 푸시 시 LFS 포인터를 감지하기 위해 파일을 검사합니다. LFS 포인터가 감지되면 GitLab은 해당 파일이 이미 LFS에 존재하는지 확인하려고 합니다. Git LFS에 별도의 서버를 사용하는 경우 이 문제가 발생하면:

• Git LFS가 로컬에 설치되어 있는지 확인합니다.

• git lfs push --all을 사용하여 수동으로 푸시하는 것을 고려합니다.

GitLab 외부에 Git LFS 파일을 저장하는 경우, 프로젝트에서 Git LFS를 비활성화할 수 있습니다.

LFS 오브젝트를 외부에 호스팅#

사용자 정의 LFS URL을 설정하여 LFS 오브젝트를 외부에 호스팅할 수 있습니다.

git config -f .lfsconfig lfs.url https://example.com/<project>.git/info/lfs

Nexus Repository와 같은 어플라이언스에 LFS 데이터를 저장하는 경우 이 방법을 사용할 수 있습니다. 외부 LFS 저장소를 사용하면 GitLab은 LFS 오브젝트를 확인할 수 없습니다. GitLab LFS 지원이 활성화된 경우 푸시가 실패합니다.

푸시 실패를 방지하려면 프로젝트 설정에서 Git LFS 지원을 비활성화할 수 있습니다. 그러나 이 방법은 다음과 같은 GitLab LFS 기능도 비활성화되므로 바람직하지 않을 수 있습니다.

• LFS 오브젝트 확인.

• LFS에 대한 GitLab UI 통합.

LFS 오브젝트 푸시 시 I/O 타임아웃#

네트워크 환경이 불안정한 경우 파일 업로드 중 Git LFS 클라이언트가 타임아웃될 수 있습니다. 다음과 같은 오류가 발생할 수 있습니다.

LFS: Put "http://example.com/root/project.git/gitlab-lfs/objects//15":
read tcp your-instance-ip:54544->your-instance-ip:443: i/o timeout
error: failed to push some refs to 'ssh://example.com:2222/root/project.git'

이 문제를 해결하려면 클라이언트 활동 타임아웃을 더 높은 값으로 설정합니다. 예를 들어 타임아웃을 60초로 설정하려면:

git config lfs.activitytimeout 60

포인터여야 하는데 그렇지 않은 파일 n개 발견#

이 오류는 리포지터리가 Git LFS로 파일을 추적해야 하지만 실제로는 추적하지 않고 있음을 나타냅니다. 이슈 326342는 GitLab 16.10에서 수정된 이 문제의 원인 중 하나였습니다.

문제를 해결하려면 영향을 받는 파일을 마이그레이션하고 리포지터리로 푸시합니다.

파일을 LFS로 마이그레이션합니다.

git lfs migrate import --yes --no-rewrite "<your-file>"

리포지터리로 다시 푸시합니다.

git push

선택 사항. .git 폴더를 정리합니다.

git reflog expire --expire-unreachable=now --all
git gc --prune=now

LFS 오브젝트가 자동으로 체크아웃되지 않음#

Git LFS 오브젝트가 자동으로 체크아웃되지 않는 문제가 발생할 수 있습니다. 이 경우 파일은 존재하지만 실제 콘텐츠 대신 포인터 참조를 포함합니다. 이 파일을 열면 예상되는 파일 콘텐츠 대신 다음과 같은 LFS 포인터가 표시될 수 있습니다.

version https://git-lfs.github.com/spec/v1
oid sha256:d276d250bc645e27a1b0ab82f7baeb01f7148df7e4816c4b333de12d580caa29
size 2323563

이 문제는 파일명이 .gitattributes 파일의 규칙과 일치하지 않을 때 발생합니다. LFS 파일은 .gitattributes의 규칙과 일치할 때만 자동으로 체크아웃됩니다.

git-lfs v3.6.0에서 이 동작이 변경되어 LFS 파일 매칭 방식이 최적화되었습니다.

GitLab Runner v17.7.0은 git-lfs v3.6.0을 사용하도록 기본 헬퍼 이미지를 업그레이드했습니다.

대소문자 구분이 다른 운영 체제 간에 일관된 동작을 위해 다양한 대소문자 패턴과 일치하도록 .gitattributes 파일을 조정하세요.

예를 들어, image.jpg와 wombat.JPG라는 LFS 파일이 있는 경우 .gitattributes 파일에서 대소문자 구분 없는 정규 표현식을 사용하세요.

*.[jJ][pP][gG] filter=lfs diff=lfs merge=lfs -text
*.[jJ][pP][eE][gG] filter=lfs diff=lfs merge=lfs -text

대부분의 Linux 배포판과 같이 대소문자 구분 파일시스템에서만 작업하는 경우 더 간단한 패턴을 사용할 수 있습니다. 예를 들면:

*.jpg filter=lfs diff=lfs merge=lfs -text
*.jpeg filter=lfs diff=lfs merge=lfs -text

경고: 가능한 LFS 구성 문제#

GitLab UI에 다음과 같은 경고가 표시될 수 있습니다.

Possible LFS configuration issue. This project contains LFS objects but there is no .gitattributes file.
You can ignore this message if you recently added a .gitattributes file.

이 경고는 Git LFS가 활성화되어 LFS 오브젝트를 포함하고 있지만, 프로젝트 루트 디렉터리에 .gitattributes 파일이 감지되지 않을 때 발생합니다. Git은 하위 디렉터리에 .gitattributes 파일을 배치하는 것을 지원하지만, GitLab은 루트 디렉터리에서만 이 파일을 확인합니다.

루트 디렉터리에 빈 .gitattributes 파일을 생성하는 것이 해결 방법입니다.

With Git

리포지터리를 클론합니다.

git clone <repository>
cd repository

빈 .gitattributes 파일을 생성합니다.

touch .gitattributes
git add .gitattributes
git commit -m "Add empty .gitattributes file to root directory"
git push

In the UI

• 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.

• 더하기 아이콘(+)과 New file을 선택합니다.

• Filename 필드에 .gitattributes를 입력합니다.

• Commit changes를 선택합니다.

• Commit message 필드에 커밋 메시지를 입력합니다.

• Commit changes를 선택합니다.