Git LFS 문제 해결

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

n개의 파일을 포인터로 추적해야 했지만 그렇지 않은 경우에 대한 오류

이 오류는 파일이 LFS에 의해 추적되어야 하지만 리포지터리가 LFS로 추적하고 있지 않을 때 발생합니다. 이 문제의 한 가지 가능한 이유는 다음과 같습니다: 웹 인터페이스를 통해 업로드된 파일이 LFS로 추적되지 않음

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

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

    git lfs migrate import --yes --no-rewrite "<파일명>"

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

    git push

  3. 옵션. .git 폴더를 정리합니다: 

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

오류: 리포지터리 또는 객체를 찾을 수 없음

이 오류는 몇 가지 이유로 발생할 수 있으며, 그 중 일부는 다음과 같습니다:

  • 특정 LFS 객체에 액세스할 수 있는 권한이 없는 경우

프로젝트로 푸시하거나 프로젝트에서 가져올 수 있는 권한을 확인합니다.

  • 프로젝트가 LFS 객체에 액세스할 수 없는 경우

푸시하거나 프로젝트에서 가져오려는 LFS 객체가 프로젝트에서 더 이상 사용할 수 없습니다. 해당 객체가 서버에서 제거되었을 수 있습니다.

  • 로컬 Git 리포지터리가 사라진 LFS API를 사용 중인 경우

<url>에 대한 유효하지 않은 상태: 501

Git LFS는 실패 사항을 로그 파일에 기록합니다. 프로젝트 디렉터리에서 이 로그 파일을 보려면: 

git lfs logs last

error 501 상태가 표시되면 다음과 같은 이유 때문입니다:

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

  • GitLab 서버에서 Git LFS 지원이 활성화되어 있지 않습니다. 서버에서 Git LFS가 활성화되어 있지 않은 이유에 대해 GitLab 관리자에게 문의하세요. LFS 지원을 활성화하는 방법에 대한 지침은 LFS 관리 문서에서 확인할 수 있습니다.

  • GitLab 서버에서 지원되지 않는 Git LFS 클라이언트 버전을 사용 중입니다. git lfs version으로 Git LFS 버전을 확인하세요. 프로젝트의 Git 구성을 확인하여 사용 중지된 API의 흔적이 있는지 git lfs -l로 확인하세요. 구성에서 batch = false로 설정되어 있다면 해당 라인을 제거하고 Git LFS 클라이언트를 업데이트해 보세요. 1.0.1 버전 이상만 지원됩니다.

getsockopt: 연결 거부

프로젝트로 LFS 객체를 푸시하려고 시도하면 다음과 유사한 오류가 발생한다면, LFS 클라이언트가 HTTPS를 통해 GitLab에 액세스하려고 시도하지만 실제로는 GitLab이 HTTP로 제공되고 있어서 발생한 것입니다: 

Post <URL>/info/lfs/objects/batch: dial tcp IP: getsockopt: connection refused

이 동작은 Git LFS가 Git 구성에 lfsurl이 설정되지 않은 경우 기본적으로 HTTPS 연결을 사용하기 때문에 발생합니다.

이러한 문제를 방지하려면 프로젝트 Git 구성에서 LFS URL을 설정하세요: 

git config --add lfs.url "http://gitlab.example.com/group/my-sample-project.git/info/lfs"

객체를 푸시할 때 항상 자격 증명이 필요함

note
GitLab은 8.12부터 SSH에 대한 LFS 지원을 추가했습니다. Git LFS 통신은 여전히 HTTP를 통해 이루어지지만 이제 SSH 클라이언트가 올바른 자격 증명을 Git LFS 클라이언트로 전달합니다. 사용자는 어떠한 조치도 필요하지 않습니다.

Git LFS는 모든 객체에 대해 모든 푸시에 HTTP 기본 인증으로 사용자를 인증하므로 사용자 HTTPS 자격 증명이 필요합니다.

기본적으로 Git은 사용하는 각 리포지터리에 대해 자격 증명을 기억하는 기능을 제공합니다. 자세한 내용은 공식 Git 문서를 참조하세요.

예를 들어, 예상한 시간 동안 암호를 기억하도록 Git에 지시할 수 있습니다: 

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

이렇게 하면 1시간 동안 자격 증명이 기억되며, 그 후 Git 작업에는 다시 인증이 필요합니다.

OS X를 사용하는 경우 osxkeychain을 사용하여 자격 증명을 저장하고 암호화할 수 있습니다. Windows를 사용하는 경우 wincred 또는 Microsoft의 Git Credential Manager for Windows를 사용할 수 있습니다.

사용자 자격 증명을 저장하는 다양한 방법에 대한 자세한 내용은 Git 자격 증명 리포지터리 문서에서 찾을 수 있습니다.

LFS 객체가 푸시될 때 누락됨

GitLab은 LFS 포인터를 감지하려고 파일을 확인합니다. LFS 포인터가 감지되면 GitLab은 해당 파일이 이미 GitLab의 LFS에 존재하는지 확인하려고 시도합니다.

로컬에 LFS가 설치되어 있는지 확인하고 git lfs push --all로 매뉴얼 푸시를 고려하세요.

GitLab 리포지터리 외부에 LFS 파일을 저장하고 있는 경우 프로젝트 API를 사용하여 lfs_enabled: false로 설정하여 프로젝트에서 LFS를 비활성화할 수 있습니다.

LFS 객체를 외부에서 호스팅하기

git config -f .lfsconfig lfs.url https://example.com/<프로젝트>.git와 같이 사용자 정의 LFS URL을 설정하여 LFS 객체를 외부에서 호스팅할 수 있습니다.

이 작업은 Nexus Repository와 같은 기기를 사용하여 LFS 데이터를 저장하는 경우 선택할 수 있습니다. 외부 LFS 스토어를 사용하는 경우 GitLab은 LFS 객체를 확인할 수 없습니다. 따라서 GitLab LFS 지원이 활성화되어 있으면 푸시가 실패합니다.

푸시 실패를 방지하기 위해 프로젝트 설정에서 LFS 지원을 비활성화할 수 있으며, 이로써 GitLab LFS 추가 기능(Visualizing LFS objects, LFS에 대한 UI 통합)도 비활성화됩니다.

LFS 객체를 푸시할 때 I/O 타임아웃

다음과 같은 오류가 발생할 수 있습니다: 

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

네트워크 상태가 불안정한 경우, Git LFS 클라이언트는 파일을 업로드하려고 시도할 때 시간 제한이 되어 파일을 업로드하는 데 실패할 수 있습니다.

이 문제를 해결하려면 클라이언트 활동 타임아웃을 더 높은 값으로 설정하세요.

예를 들어, 타임아웃을 60초로 설정하려면: 

git config lfs.activitytimeout 60