✅ Git Subtree란?
Git Subtree는 별도의 Git 저장소(레포지토리)를 하나의 레포지토리 내부 특정 디렉터리에 병합하여 사용하는 방식입니다. Submodule과 비슷하게 별도의 저장소를 연결하지만, 서브모듈(Submodule)이 참조만 하는 반면, Subtree는 다른 저장소를 직접 내 레포지토리에 복사해서 통합 관리하는 방식입니다.
🌱 Git Subtree의 특징
- 독립된 저장소 통합
- 외부 레포지토리의 내용을 내 레포지토리의 특정 폴더로 통합할 수 있습니다.
- 히스토리 통합 및 유지 가능
- 외부 레포지토리의 히스토리를 내 레포지토리에 통합하여 보존할 수 있습니다.
- 관리 간편성
- 서브모듈에 비해 관리가 비교적 간단하고 직관적입니다.
- 복사 기반 관리 방식
- 히스토리를 유지하면서도 실제 내용을 복사하여 통합하기 때문에, 독립성을 유지하면서도 내 레포지토리의 일부로 자연스럽게 관리할 수 있습니다.
📌 Submodule과 Subtree 비교
항목 Git Submodule Git Subtree
| 통합 방식 | 별도 저장소를 참조(link) | 저장소의 내용을 복사하여 통합 |
| 히스토리 관리 | 개별 히스토리 유지 (서브모듈) | 내 저장소의 히스토리에 통합 가능 |
| 독립성 | 독립성 강함 (별도 모듈) | 독립성 보통 (일부 독립적 관리 가능) |
| 관리 난이도 | 높음 (복잡한 설정 및 관리 필요) | 비교적 쉬움, 직관적 |
| 브랜치 관리 | 독립적 브랜치 관리 가능 (서브모듈에서 직접 관리) | 브랜치 관리가 내 저장소와 통합되어 관리 |
🚩 Git Subtree 기본 사용법
1️⃣ 다른 레포지토리의 내용을 가져오기 (추가)
git subtree add --prefix=<폴더명> <외부 저장소 URL> <브랜치명> --squash
- <폴더명>: 현재 레포지토리에서 외부 레포지토리를 위치시킬 디렉터리 경로
- <외부 저장소>: 통합할 외부 저장소 URL
- –prefix: 가져올 폴더 경로를 지정하는 옵션
- –squash: 히스토리를 압축하여 가져올 경우 사용 (선택사항)
예시:
git subtree add --prefix=auth-module https://gitlab.example.com/libs/auth.git main
이렇게 하면 내 레포지토리의 auth-module 폴더로 auth.git 저장소의 내용이 추가되며 히스토리도 유지됩니다.
2️⃣ 추가한 subtree를 업데이트 (변경사항 병합)
외부 저장소의 변경사항을 내 저장소에 병합하려면 다음과 같이 수행합니다.
git subtree pull --prefix=<폴더명> <외부 저장소> <브랜치> --squash
예시:
git subtree pull --prefix=auth-module https://gitlab.example.com/libs/auth.git main --squash
- 외부 저장소의 최신 커밋을 가져와 내 저장소에 병합합니다.
3️⃣ 변경 사항을 외부 저장소로 푸시하기
내 저장소에서 작업한 변경사항을 외부 저장소로 푸시할 때는 다음과 같이 수행합니다.
git subtree push --prefix=<폴더명> <외부 저장소> <브랜치>
예시:
git subtree push --prefix=auth-module https://gitlab.example.com/libs/auth.git main
단, 외부 저장소에 대한 권한이 있어야 합니다.
📌 Subtree vs. Submodule 비교 (사용 시나리오)
비교 항목 Submodule Subtree
| 독립된 개발 및 관리 | ✅ 강력함 | ⚠️ 중간 |
| 히스토리 관리 복잡성 | ⚠️ 중간 | ✅ 단순함 |
| 명령어 및 관리 편의성 | ⚠️ 중간 | ✅ 쉬움 |
| 업데이트와 병합 용이성 | ⚠️ 중간 | ✅ 편리함 |
| 재사용성 | ✅ 높음 | ⚠️ 보통 |
🎯 Git Subtree 사용 추천 상황
- 외부 모듈을 통합하여 프로젝트의 일부로써 관리하고 싶은 경우
- 독립된 저장소를 내 프로젝트에 완전히 흡수하여 관리하고자 할 때
- Submodule의 관리 복잡성이 부담스럽지만 독립된 히스토리와 통합이 필요할 때
결론적으로:
- 서브트리는 외부 레포지토리의 내용을 내 프로젝트의 일부처럼 관리할 때 가장 편리한 기능입니다.
- 특히 모듈 통합, 내부화된 라이브러리 관리, 모듈화된 프로젝트 관리 등에 유용합니다.
