Git LFS와 함께 Git 저장소를 Git LFS로 이전하기

경고: 다음 문서는 더 이상 사용되지 않습니다. 아래 문서에 문서화된 방법 대신에 git lfs migrate를 사용하는 것을 권장합니다.

Git LFS를 사용하면 Git 저장소의 크기를 줄이고 성능을 향상시킬 수 있습니다.

그러나 이미 저장소에 있는 큰 파일을 Git LFS에 추가하여도 실제로 저장소의 크기가 줄지는 않습니다. 왜냐하면 파일은 여전히 이전 커밋에서 참조되기 때문입니다.

이 문서에서 설명하는 방법을 통해, 먼저 오픈 소스 커뮤니티가 유지보수하는 BFG와 같은 도구를 사용하여 Git LFS로 이전한 후 미러 저장소를 통해 저장소의 이력을 정리하고, 마지막으로 새로운 이진 파일이 추가되는 것을 방지하기 위해 LFS 추적 규칙을 생성할 수 있습니다.

이 자습서는 BFG를 사용하여 저장소를 Git LFS로 이전하는 방법에서 영감을 받았습니다. Git LFS에 대한 자세한 정보는 아래의 참고 자료를 참조하세요.

경고: 이 가이드에 설명된 방법은 Git 이력을 다시 작성합니다. 시작하기 전에 저장소를 백업하고 자신의 책임하에 사용하세요.

사전 요구 사항

시작하기 전에 다음을 확인하세요:

  • 원하는 파일을 변환할 수 있는 충분한 LFS 저장 공간이 있는지 확인하십시오. 모든 파일의 전체 이력을 위한 저장소가 필요합니다.
  • 저장소를 공유하는 모든 팀원이 모든 변경 사항을 푸시했는지 확인하세요. 이 방법을 적용하기 전에 저장소를 기반으로 한 브랜치를 병합할 수 없습니다.

이 자습서를 따르려면 다음이 필요합니다:

  • 기존 Git 저장소의 관리자 역할 및 명령줄을 통한 LFS로 이전하려는 권한
  • 로컬에 설치된 Git 및 Java Runtime Environment (Java 7 이상)

  • 로컬에 설치된 BFG: 

     brew install bfg

  • 로컬에 설치된 Git LFS: 

     brew install git-lfs

참고: 이 가이드는 macOS Mojave에서 테스트되었습니다.

단계

예를 들어 git@gitlab.com:gitlab-tests/test-git-lfs-repo-migration.git와 같은 예시 상위 프로젝트를 고려하십시오.

  1. 저장소를 백업하세요:

    무언가 잘못되었을 경우에 대비하여 저장소의 사본을 만듭니다.

  2. --mirror 플래그로 저장소 복제:

    미러 플래그를 사용하여 복제하면 베어(repository) 저장소가 만들어집니다. 이로써 저장소 내의 모든 브랜치를 얻을 수 있습니다.

    지역 저장소를 만들고, 이전에 업그레이드 된 프로젝트를 미러링(예시인 test-git-lfs-repo-migration.git)하는 디렉터리를 만듭니다: 

    git clone --mirror git@gitlab.com:gitlab-tests/test-git-lfs-repo-migration.git

  3. BFG로 Git 이력 변환: 

    bfg --convert-to-git-lfs "*.{png,mp4,jpg,gif}" --no-blob-protection test-git-lfs-repo-migration.git

    모든 이력을 스캔하고 해당 확장자를 가진 파일을 찾은 다음 LFS 포인터로 변환합니다.

  4. 저장소의 정리: 

    # 미러 저장소 디렉터리로 변경:
cd test-git-lfs-repo-migration.git

# 저장소 정리:
git reflog expire --expire=now --all && git gc --prune=now --aggressive

    또한 저장소를 더 정리하는 방법을 확인할 수 있지만, 이 가이드의 목적에는 필요하지 않습니다.

  5. 미러 저장소에 Git LFS 설치: 

    git lfs install

  6. 기본 브랜치 보호 해제, 이렇게 함으로써 다시 작성된 저장소를 강제로 푸시할 수 있습니다:

    1. 프로젝트의 설정 > 저장소로 이동하고 보호된 브랜치를 확장합니다.
    2. 보호된 브랜치를 찾아서 기본 브랜치를 보호 해제하세요.

  7. GitLab에 강제 푸시: 

    git push --force

  8. LFS로 추적할 파일 지정: 

    # /tmp 디렉토리로 변경
cd /tmp

# 저장소 복제
git clone git@gitlab.com:gitlab-tests/test-git-lfs-repo-migration.git

# 상위 프로젝트 디렉터리로 이동:
cd test-git-lfs-repo-migration

# 미러에서 강제 푸시 후 로컬 복사본을 원격 저장소의 `main`으로 재설정해야 할 수 있습니다:
git reset --hard origin/main

# LFS로 파일 추적:
git lfs track "*.gif" "*.png" "*.jpg" "*.psd" "*.mp4" "img/"

# .gitattributes에 대한 변경 사항을 푸시
git add .gitattributes && git commit -m '.gif,.png,.jpg,.psd,.mp4 및 img/ 추적' && git push

    이제 변환한 기존 파일 및 추가한 새 파일이 모두 LFS로 올바르게 추적됩니다.

  9. 기본 브랜치 다시 보호:

    1. 프로젝트의 설정 > 저장소로 이동하고 보호된 브랜치를 확장합니다.
    2. 브랜치 드롭다운 목록에서 기본 브랜치를 선택하고 푸시 및 병합 허용 및 병합 허용 허용 규칙을 설정하세요.
    3. 보호를 선택하세요.

참고 자료

  • Git LFS 시작하기
  • GitLab Git LFS 사용자 문서
  • GitLab Git LFS 관리자 문서
  • 기존 저장소를 Git LFS로 이전하는 대체 방법