Git LFS 및 Perforce 저장소를 Lore로 마이그레이션하는 단계별 가이드
대용량 게임 에셋 관리를 위해 Git LFS 및 Perforce(P4) 저장소를 Lore로 무중단 마이그레이션하는 구체적인 절차, CI/CD 파이프라인 전환, 롤백 전략을 정리합니다.
TL;DR
대용량 바이너리 에셋과 소스코드가 혼재된 대규모 게임 프로젝트를 Lore로 이전하면 Git LFS의 포인터 동기화 병목과 Perforce의 고비용 인프라 운영 오버헤드를 동시에 해결할 수 있습니다.
마이그레이션은 1) 무결성 검증 및 메타데이터 맵핑, 2) 히스토리 및 바이너리 블롭(Blob) 변환 임포트, 3) CI/CD 빌드 에이전트 캐시 재구성 및 락(Lock) 정책 전환의 3단계로 진행되며 듀얼 싱크(Dual-Sync) 체계를 통해 빌드 무중단 상태를 유지할 수 있습니다.
게임 개발 파이프라인에서 왜 VCS 마이그레이션을 고민하는가?
게임 개발 프로젝트가 고도화될수록 3D 모델, 4K/8K 텍스처, 사운드 뱅크, 프리팹과 같은 바이너리 에셋의 비중이 기하급수적으로 증가합니다.
전통적인 소스 코드 중심의 Git 환경에서는 LFS(Large File Storage) 확장 기능을 사용하더라도 클론/체크아웃 속도 저하와 복잡한 포인터 누락 문제가 발생하기 쉽습니다. 반면 Perforce(Helix Core)는 바이너리 처리와 배타적 잠금(Exclusive Checkout)에 강점이 있지만 브랜치 관리 비용이 높고 분산 오프라인 작업이 어렵습니다.
Lore는 Git의 유연한 분산 브랜치 워크플로와 Perforce의 고성능 바이너리 청크 스트리밍 및 파일 락 제어를 단일 엔진으로 결합한 차세대 게임 전용 버전 관리 시스템입니다. 프로젝트를 Lore로 이전하면 CI/CD 빌드 머신의 에셋 동기화 속도를 비약적으로 단축하고 라이브 패치 파이프라인의 안정성을 높일 수 있습니다.
| 비교 항목 | Git + Git LFS | Perforce (Helix Core) | Lore |
|---|---|---|---|
| 바이너리 처리 방식 | 메타데이터 포인터 치환 | 서버 중앙 저장 및 스트리밍 | 콘텐츠 기반 청크 분할 스트리밍 |
| 브랜치 오버헤드 | 가볍고 빠름 (로컬 브랜치) | Streams 기반, 서버 리소스 소모 | 가상화 브랜치 및 부분 체크아웃 |
| 파일 잠금 (Locking) | LFS Lock API (느린 폴링) | 서버 중심 원자적 잠금 | 즉시 잠금 동기화 및 충돌 감지 |
| CI/CD 체크아웃 속도 | Smudge 필터로 인한 병목 | 빠름 (중앙 프록시 활용) | 분산 P2P/로컬 캐시 청킹으로 초고속 |
| 인프라 유지보수 | LFS 서버 분리로 복잡도 증가 | 전용 서버 및 라이선스 비용 높음 | 모듈형 분산 스토리지 및 클라우드 네이티브 |
마이그레이션 파이프라인 아키텍처
이전 작업을 안전하게 수행하기 위해서는 소스 저장소의 커밋/체인지리스트(Changelist) 히스토리, 브랜치 계층 구조, 바이너리 LFS 포인터, 파일 락 상태를 원자적으로 파싱하여 Lore 스토리지 레이어로 변환해야 합니다.
flowchart LR
subgraph Source [기존 저장소]
GL[Git LFS Repository] --> |LFS Pointer & Commit Tree| IE[Inspection Engine]
P4[Perforce Helix Depot] --> |Changelist & Typemap| IE
end
subgraph Transform [변환 파이프라인]
IE --> |무결성 검사| VAL[Validation & Hash Check]
VAL --> |청크 분할 및 역직렬화| CONV[Lore Migration Pipeline]
end
subgraph Target [Lore 시스템]
CONV --> LMeta[(Lore Metadata DB)]
CONV --> LBlob[(Lore Object Storage)]
CONV --> LLock[Live Lock Registry]
end
Git LFS 저장소를 Lore로 변환하는 4단계 절차
Git LFS 프로젝트를 Lore로 이전할 때는 포인터 파일만 존재하고 실제 바이너리 오브젝트가 누락되는 ‘LFS 미러 불일치’ 현상을 사전에 방지해야 합니다.
1단계: LFS 무결성 검증 및 히스토리 정리
먼저 원격 저장소의 모든 LFS 오브젝트가 로컬에 완전하게 캐시되어 있는지 확인하고 누락된 객체를 일괄 다운로드합니다.
# 모든 원격 브랜치 및 태그의 LFS 오브젝트 완전 동기화
git fetch --all --tags
git lfs fetch --all
# LFS 포인터와 실제 바이너리 무결성 검증
git lfs fsck2단계: LFS 추적 규칙(.gitattributes) 분석
.gitattributes에 정의된 필터 설정을 추출하여 Lore의 에셋 정책 정의 파일(lore.attributes)로 변환합니다.
# .gitattributes 예시
*.png filter=lfs diff=lfs merge=lfs -text
*.fbx filter=lfs diff=lfs merge=lfs -text lockable
*.psd filter=lfs diff=lfs merge=lfs -text lockable3단계: lore import-git 명령을 통한 변환 실행
Lore CLI 도구를 사용하여 Git 히스토리와 LFS 바이너리를 인덱싱하여 새 Lore 저장소로 변환합니다.
# Git LFS 저장소를 Lore로 변환
lore import-git \
--source="/path/to/git-repo" \
--target="lore://storage.internal/unreal-project" \
--include-lfs \
--convert-locks \
--threads=164단계: 워킹 트리(Working Tree) 및 체크아웃 검증
변환 완료 후 클라이언트 환경에서 체크아웃을 수행하고 에셋 해시 일치 여부를 대조합니다.
lore clone lore://storage.internal/unreal-project
cd unreal-project
lore status
lore verify-integrityPerforce(P4) 저장소를 Lore로 변환하는 4단계 절차
Perforce 저장소 이전 시에는 typemap에 설정된 +l(배타적 잠금), +k(키워드 확장 방지) 등의 속성을 Lore 메타데이터 규칙으로 정확히 매핑하는 것이 핵심입니다.
1단계: Depot 경로 및 Changelist 범위 설정
마이그레이션 대상 Stream 또는 Depot 경로를 확인하고 이전할 Changelist 범위를 확정합니다.
# P4 변경 이력 및 Typemap 확인
p4 typemap -o > p4_typemap.txt
p4 changes -m 500 //depot/main/GameProject/...2단계: Typemap 규칙을 Lore 에셋 정책으로 매핑
P4 속성을 Lore가 인식할 수 있는 규칙으로 정의합니다. 예를 들어 P4의 binary+l 속성은 Lore의 lock=exclusive 정책으로 치환됩니다.
# lore.rules 매핑 정의
//depot/.../*.uasset -> asset_type=binary, lock=exclusive
//depot/.../*.umap -> asset_type=binary, lock=exclusive
//depot/.../*.cpp -> asset_type=text, merge=auto3단계: lore import-p4 실행
Perforce 서버의 메타데이터와 Depot 파일들을 스트리밍하여 Lore 블롭 스토리지로 적재합니다.
lore import-p4 \
--p4port="ssl:perforce.company.com:1666" \
--p4user="build_admin" \
--p4client="migration_workspace" \
--depot-path="//depot/main/GameProject/..." \
--target="lore://storage.internal/game-project" \
--start-change=1 \
--preserve-timestamps4단계: 사용자 권한 및 락 레지스트리 동기화
현재 P4에서 활성화된 오픈 파일(Opened/Locked Files) 상태를 조회하여 Lore의 분산 락 테이블로 이관합니다.
# 활성 P4 락 추출 후 Lore 락 엔진에 반영
p4 opened -a //depot/main/GameProject/... > opened_locks.txt
lore lock import --file=opened_locks.txt
CI/CD 빌드 파이프라인 및 라이브 운영 전환 전략
형상관리 시스템 전환 시 빌드 머신들의 체크아웃 스크립트와 캐시 구조를 갱신하지 않으면 라이브 패치 배포가 지연될 수 있습니다.
Jenkins / GitHub Actions 스크립트 갱신
기존 Git LFS의 smudge 단계나 Perforce p4 sync 스크립트를 Lore 전용 CLI 호출로 교체합니다.
# GitHub Actions / Jenkins 파이프라인 단계 수정
steps:
- name: Setup Lore CLI
uses: lore-vcs/setup-lore-action@v1
with:
version: "2.4.0"
- name: Checkout Project via Lore
run: |
lore init-cache --path="/opt/lore-cache" --max-size=500GB
lore sync --revision="${{ github.sha }}" --depth=shallow --parallel=8듀얼 싱크(Dual-Sync) 기반 롤백 플랜
전환 당일 발생할 수 있는 클라이언트 이슈에 대비하여 최소 2주간 듀얼 싱크 브리지를 운영합니다.
- 개발자 커밋 주체 전환: 메인 개발팀의 커밋 권한을 Lore로 일괄 이전합니다.
- 자동 단방향 미러링: Lore의 새로운 커밋 및 에셋 변경 사항을 기존 Git/P4 저장소로 자동 동기화하는 미러 봇을 가동합니다.
- 비상 롤백 절차: 심각한 장애 발생 시 미러 봇을 중단하고 Git/P4의 쓰기 권한을 즉시 복구합니다.
자주 묻는 질문 (FAQ)
Q1. 마이그레이션 도중 이전 작업이 실패하면 기존 저장소 데이터가 훼손되나요?
아닙니다. Lore의 import-git 및 import-p4 도구는 원본 저장소에 대해 순수 읽기(Read-Only) 모드로 동작합니다. 변환 과정에서 네트워크 단절이나 디스크 용량 부족으로 작업이 중단되더라도 기존 Git이나 Perforce의 히스토리와 파일에는 아무런 영향을 주지 않으며 Lore 임포트 세션은 재개(Resume) 옵션을 통해 중단 지점부터 다시 실행할 수 있습니다.
Q2. 수십만 개의 커밋과 체인지리스트 히스토리가 빠짐없이 보존되나요?
예, 작성자(Author), 커밋 시각(Timestamp), 커밋 메시지, 브랜치 병합(Merge) 토폴로지가 1:1로 보존됩니다. 다만 과거 커밋에서 삭제된 불필요한 대용량 임시 바이너리까지 모두 가져올 필요가 없다면 --prune-unreachable 옵션을 사용하여 저장소 용량을 크게 최적화할 수 있습니다.
Q3. 전환 후 CI/CD 빌드 머신의 체크아웃 시간은 얼마나 단축되나요?
프로젝트 규모에 따라 차이가 있으나 수백 기가바이트(GB) 단위의 언리얼/유니티 프로젝트 기준으로 Git LFS 대비 평균 60~75%의 체크아웃 시간 단축 효과를 보입니다. Lore는 로컬 청크 캐시와 병렬 블롭 스트리밍을 지원하므로 변경되지 않은 대용량 에셋의 불필요한 재다운로드를 원천 차단합니다.
