Git Subtree란?

✅ 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의 관리 복잡성이 부담스럽지만 독립된 히스토리와 통합이 필요할 때

---

결론적으로:

• 서브트리는 외부 레포지토리의 내용을 내 프로젝트의 일부처럼 관리할 때 가장 편리한 기능입니다.
• 특히 모듈 통합, 내부화된 라이브러리 관리, 모듈화된 프로젝트 관리 등에 유용합니다.