[Git] 깃허브 미러링: 커밋 내역을 살려 레포지토리를 분리하는 기술

하나의 GitHub 레포지토리가 점차 커지면서, 기능 단위 또는 모듈 단위로 분리할 필요가 생기는 경우가 많다. 이때 단순히 디렉터리를 복사해 새로운 레포에 업로드하는 방식은 기존 커밋 이력(히스토리)을 보존하지 못한다는 단점이 있다. 이 글에서는 Git의 mirroring 기술을 활용해, 커밋 내역까지 유지하면서 특정 디렉터리를 별도 레포지토리로 분리하는 방법을 소개하려 한다!

 

 

 

사용 기술: git filter-repo (또는 git filter-branch)

git filter-repo란?

git filter-repo는 Git 공식이 권장하는 히스토리 리라이팅 툴로, 특정 디렉터리만 추출하거나 파일을 제거할 때 기존 커밋 이력을 유지한 채 작업할 수 있게 해준다.

 

 

(전체 흐름 요약)

1. 원본 레포 복제 (미러링 방식)
2. 특정 디렉터리만 남기고 나머지 제거
3. 새 레포에 푸시

 

예시: skaxis의 /ai 디렉터리를 분리

1. 원본 레포 미러링 복제

git clone --mirror https://github.com/SK-AXIS/SK-AXIS.git
cd SK-AXIS.git

 

 

2. git filter-repo로 특정 디렉터리만 추출

git filter-repo --subdirectory-filter ai

 

 

3. 새 원격 레포지토리 설정 및 푸시

git remote set-url origin https://github.com/SK-AXIS/SK-AXIS-FASTAPI.git
git push --mirror

 

--mirror 옵션으로 브랜치, 태그 포함 전체 이력을 새 레포에 푸시할 수 있다

 

 

 

주의할 점

• git filter-repo는 기존 레포를 직접 변경하므로 복제본에서 실행하는 것이 안전하다
• git filter-repo는 pip install git-filter-repo 또는 GitHub에서 바이너리 설치 가능하다
• GitHub에서 기존 레포의 이슈, PR은 자동으로 이전되지 않으며, 별도로 백업하거나 gh CLI 등을 활용해야 한다

 

 

(+ 참고) git subtree split - 브랜치 하나만 복사

보다 간단하게 분리하고 싶은 경우, 다음 명령어도 가능하다

git subtree split -P ai -b ai-branch
git checkout ai-branch
git remote add new-origin https://github.com/SK-AXIS/SK-AXIS-FASTAPI.git
git push new-origin ai-branch:main

 

하지만 subtree split은 브랜치 하나만 복사되며, tag, remote, 전체 이력 구조가 미러링되지 않기 때문에 복잡한 이력이 필요한 경우 filter-repo 방식이 더 적합하다!!!

 

 

 

 

 

(실제 미러링 기술 적용 프로젝트 주소)

https://github.com/orgs/SK-AXIS/repositories

SK-AXIS

기존의 SK-AXIS 레포지토리에서 ai, client, server가 같이 작업하다 분리하게 된 구조이다!