스낵깃 🍪 - 협업편 #4: Git Submodule - 여러 레포를 한 프로젝트에서 다루는 법

Git을 사용하다 보면 한 프로젝트에서 여러 개의 저장소를 함께 관리해야 하는 상황이 생긴다.

예를 들어, 대규모 프로젝트, MSA(Microservices Architecture), 서드파티 라이브러리 직접 관리 등이 해당된다.

이때, 여러 저장소를 하나의 프로젝트에서 깔끔하게 유지할 수 있도록 도와주는 기능이 바로 Git Submodule이다.

 

하지만 막상 사용해보려 하면 Git Submodule이 정말 필요한가? 라는 고민이 들 수 있다.

Subtree, 패키지 매니저(npm, pip, maven) 같은 대안도 있기 때문이다.🤔

 

이 글에서는 Git Submodule이 무엇인지, 언제 사용해야 하는지, 그리고 실제로 어떻게 활용하는지 알아본다. 

---

Git Submodule vs Git Subtree vs 패키지 매니저, 뭐가 다를까?

 

Git Submodule을 도입하기 전에 비슷한 기능을 제공하는 다른 방법들과 비교해볼 필요가 있다.

방식	특징	사용 사례
Git Submodule	독립적인 레포를 링크하여 관리	외부 라이브러리 포함, 독립적인 프로젝트 유지
Git Subtree	외부 레포의 코드를 가져와 병합	코드 변경 사항을 쉽게 반영해야 하는 경우
패키지 매니저 (npm, pip, maven 등)	별도의 패키지로 관리	라이브러리를 버전별로 유지하고 싶을 때

 

한마디로 정리하면?

• Submodule: 외부 프로젝트를 독립적으로 유지하면서 특정 버전 상태를 관리해야 할 때 적절

• Subtree: 외부 코드를 내 레포에 통합하고, 변경 사항을 쉽게 가져와야 할 때 적절

• 패키지 매니저: 라이브러리를 별도로 유지하며 쉽게 설치·관리하고 싶을 때 적절

 

그러므로, 서브모듈은 독립적인 프로젝트를 포함할 때 적합하지만, 자주 업데이트해야 하는 경우라면 서브트리나 패키지 매니저가 더 나을 수 있다.

---

🛠️ Git Submodule 사용법

 

1️⃣ 서브모듈 추가하기

 

Submodule을 추가하는 기본 명령어는 다음과 같다.

git submodule add <서브모듈_레포_URL> <서브모듈_디렉토리_경로>

예를 들어, common-library라는 라이브러리를 libs/common-library 폴더에 추가하려면 다음과 같이 실행한다.

git submodule add https://github.com/example/common-library.git libs/common-library
git commit -m "Add submodule: common-library"

 

이제 libs/common-library 폴더에 common-library 레포가 포함된다.

 

---

2️⃣ 서브모듈이 있는 프로젝트를 클론할 때

 

서브모듈이 포함된 프로젝트를 새롭게 클론하면 기본적으로 서브모듈이 포함되지 않는다.

따라서 서브모듈을 함께 가져오려면 --recurse-submodules 옵션을 사용해야 한다.

git clone --recurse-submodules <레포_URL>

 

이미 클론한 경우, 서브모듈을 가져오려면 다음 명령어를 실행한다.

git submodule update --init --recursive

 

 

---

3️⃣ 서브모듈 업데이트하기

 

Submodule은 독립적인 저장소이므로, 메인 프로젝트와 자동으로 동기화되지 않는다.

따라서 최신 상태로 유지하려면 다음 명령어를 실행해야 한다.

git submodule update --remote

 

서브모듈이 특정 브랜치를 따라가도록 설정할 수도 있다.

cd <서브모듈_디렉토리>
git checkout main
cd ..
git add <서브모듈_디렉토리>
git commit -m "Update submodule to latest version"

---

4️⃣ 서브모듈 삭제하는 방법

 

서브모듈을 제거하려면 몇 가지 단계를 거쳐야 한다.

git submodule deinit -f libs/common-library
rm -rf .git/modules/libs/common-library
git rm -f libs/common-library
git commit -m "Remove submodule: common-library"

 

이제 서브모듈이 완전히 제거된다.

 

---

⚠️ Git Submodule 사용 시 주의할 점

 

✔ 관리 난이도 증가

    : 서브모듈은 기본 Git 워크플로우와는 다르게 작동하므로, 팀원들에게 추가적인 학습이 필요하다.

 

✔ CI/CD 환경에서 문제 발생 가능성

    : 일부 CI/CD 파이프라인에서는 서브모듈을 자동으로 가져오지 않으므로, .gitmodules를 관리하는 방법을 숙지해야 한다.

 

✔ 프로젝트 전반적인 복잡도 증가

    : 단순한 프로젝트라면 서브모듈보다 패키지 매니저를 활용하는 것이 훨씬 간단할 수 있다.

 

---

🚀 마무리하며…

 

Git Submodule은 한 프로젝트에서 여러 개의 독립적인 Git 저장소를 함께 관리해야 할 때 유용한 기능이다.

특히 대규모 프로젝트나 MSA 환경에서 특정 모듈을 독립적으로 유지할 경우 적절한 솔루션이 될 수 있다.

 

그렇다면,

❓ 서브모듈이 적절한 경우❓ 

✔ 특정 외부 프로젝트를 유지하면서도 독립적인 버전 관리를 해야 할 때

✔ 서드파티 라이브러리를 직접 포함하여 사용해야 할 때

✔ 프로젝트 간 강한 의존성이 있는 경우 (ex: 내부 공통 라이브러리)

 

적절하다.

 

하지만, 서브모듈을 과하게 사용하면 프로젝트가 불필요하게 복잡해질 수 있으므로 신중하게 도입하는 것이 중요하다.

결국, 팀 내에서 서브모듈이 꼭 필요한지 논의하고 결정하는 것이 가장 좋은 방법이다.

 

다음 글에서는 Git Subtree와의 차이점과 실제 사용 사례를 더 깊이 분석할 예정이다.