• 사전 요구 사항
• 절차
• 참고 자료

Git LFS와 BFG를 사용하여 Git 리포지터리를 이전하기

Git LFS를 사용하면 Git 리포지터리의 크기를 줄이고 성능을 향상시킬 수 있습니다.

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

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

이 튜토리얼은 BFG를 사용하여 리포지터리를 Git LFS로 이전하는 방법에서 영감을 받았습니다. Git LFS에 대한 자세한 정보는 아래의 참고 자료를 참조하세요.

사전 요구 사항

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

• 변환하려는 파일에 충분한 LFS 저장 공간이 있는지 확인하세요. 리포지터리의 전체 기록에 대한 저장 공간이 필요합니다.
• 같이 사용하는 팀원들이 모든 변경 사항을 푸시했는지 확인하세요. 이 방법을 적용하기 전에 리포지터리를 기반으로 한 브랜치는 Merge할 수 없습니다.

이 튜토리얼을 따르려면 다음이 필요합니다:

• 기존 Git 리포지터리에 대한 Maintainer 역할 및 명령 줄을 통한 액세스
• 로컬에 설치된 Git 및 Java Runtime Environment (Java 7 이상)

• 로컬에 설치된 BFG:

   brew install bfg
  

• 로컬에 설치된 Git LFS:

   brew install git-lfs
  

절차

예를 들어 git@gitlab.com:gitlab-tests/test-git-lfs-repo-migration.git와 같은 상위 프로젝트를 고려해 보겠습니다.

1. 리포지터리를 백업하세요:

   무언가 잘못되었을 경우를 대비해 리포지터리의 사본을 만듭니다.

2. --mirror 옵션을 사용하여 리포지터리를 복제하세요:

   미러 플래그를 사용하여 별칭 리포지터리를 만듭니다. 이렇게 하면 리포지터리 내의 모든 브랜치를 가져올 수 있습니다.

   이는 <repo-name>.git라는 디렉터리를 만들어서 상위 프로젝트를 반영한 미러 리포지터리를 만듭니다. (예: 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. GitLab에서 강제 푸시하려면 기본 브랜치의 보호 해제를 해야합니다:

   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 'Track .gif,.png,.jpg,.psd,.mp4 and img/' && git push
   

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

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

   1. 프로젝트의 설정 > 리포지터리로 이동하여 보호된 브랜치를 확장합니다.
   2. Branch 드롭다운 디렉터리에서 기본 브랜치를 선택하고 푸시 및 Merge 허용 및 Merge 허용 규칙을 설정합니다.
   3. 보호를 선택합니다.

참고 자료

• Git LFS 시작하기
• GitLab Git LFS 사용자 설명서
• GitLab Git LFS 관리자 설명서
• 기존 리포지터리를 Git LFS로 이전하는 대체 방법