Git Submodule이란?

Git Submodule은 하나의 Git 레포지토리 내부에서 다른 독립된 Git 레포지토리를 연결하여 사용할 수 있도록 하는 기능입니다.
주로 외부 라이브러리나 공통 모듈을 별도의 레포지토리로 관리한 후 이를 포함하는 형태로 사용합니다.

---

🧩 Git Submodule의 사용 목적

• 독립적으로 관리되는 외부 라이브러리, 프레임워크를 통합할 때 사용
• 여러 프로젝트에서 공통으로 쓰는 모듈을 공유할 때 효율적
• 개별적인 Git 히스토리와 독립적 관리 가능

---

🚩 Submodule의 동작 원리

• 메인 레포지토리(parent repository)는 서브모듈의 특정 커밋 해시를 저장합니다.
• 서브모듈은 별도의 독립적인 레포지토리로 존재하며, 메인 레포지토리는 이 레포지토리를 참조만 합니다.
• 서브모듈을 업데이트하면, 메인 레포지토리에서도 업데이트된 커밋을 명시적으로 기록해주어야 반영됩니다.

Main Repo
├── README.md
└── src
    └── common-library (submodule)

---

🚀 Submodule 기본 사용법

1️⃣ Submodule 추가하기

git submodule add https://gitlab.example.com/your-library.git path/to/submodule

• your-library.git: 서브모듈로 가져올 GitLab의 외부 레포지토리 URL
• path/to/submodule: 서브모듈이 추가될 디렉터리 위치

예시:

git submodule add https://gitlab.example.com/libs/auth-lib.git libs/auth

2️⃣ 서브모듈 클론하기

메인 레포지토리 클론 시 서브모듈은 기본적으로 빈 상태로 클론됩니다. 명시적으로 아래 명령어를 실행하여 클론합니다.

git clone --recurse-submodules https://gitlab.example.com/main-project.git

또는 이미 클론한 레포지토리라면:

git submodule update --init --recursive

3️⃣ Submodule 최신 코드로 업데이트하기

서브모듈 내 코드를 최신 상태로 업데이트할 때는:

cd path/to/submodule
git checkout main # 또는 원하는 브랜치
git pull origin main

cd ../../ # 메인 레포로 이동
git add path/to/submodule
git commit -m "Update submodule to latest commit"
git push

• 서브모듈을 업데이트하면 메인 레포에서 별도의 commit을 해야 합니다. (서브모듈의 commit hash 변경 기록)

---

📌 서브모듈 상태 확인하기

서브모듈 상태를 확인하려면 아래 명령어를 사용합니다.

git submodule status

출력 예시:

 e5f7c1a... path/to/submodule (heads/main)

---

🛠 서브모듈 제거하기

서브모듈을 제거할 때는 조금 복잡한 절차가 필요합니다.

예시:

git submodule deinit path/to/submodule
git rm path/to/submodule
rm -rf .git/modules/path/to/submodule
git commit -m "Removed submodule"

---

⚠️ Submodule 주의사항

• 서브모듈은 특정 커밋을 참조하므로, 메인 레포지토리를 클론할 때 항상 최신 상태로 가져오지 않을 수 있습니다.
• 여러 서브모듈을 관리하다 보면 관리 복잡성이 증가할 수 있습니다.
• 서브모듈의 커밋이 변경되었을 때 반드시 메인 레포지토리에 변경 내역을 commit 해야 합니다.

---

🎯 Submodule 사용을 추천하는 상황

• 여러 프로젝트 간 공통적으로 사용하는 공통 모듈을 별도 관리할 때
• 외부 라이브러리를 독립적으로 관리 및 유지보수할 필요가 있을 때
• 분리된 모듈로서 독립된 배포 및 개발이 필요할 때

---

이러한 방식으로 Git Submodule 기능을 효율적으로 활용할 수 있습니다.