Git Submodule 정리하기 (with 예제)

프로젝트를 하다 보면 때때로 이런 상황이 생긴다.

• 공통 유틸 저장소를 여러 프로젝트에서 같이 써야 한다
• 외부 라이브러리를 수정 가능한 상태로 포함하고 싶다
• 특정 커밋 버전을 정확히 고정하고 싶다

이럴 때 사용하는 기능이 바로 Git Submodule이다.

 

Git Submodule이란?

Git Submodule은 다른 Git 저장소를 현재 저장소 안에 포함시키는 기능이다.

단순히 코드를 복사해 넣는 것이 아니라

• 별도의 Git 저장소로 관리되며
• 특정 커밋을 참조하고
• 상위 저장소는 “그 커밋을 가리키는 포인터”만 저장한다

즉 “저장소 안에 또 다른 저장소를 연결해두는 방식” 이다.

 

언제 사용하면 좋을까?

Submodule은 이런 경우에 적합하다.

• 공통 라이브러리를 여러 프로젝트에서 공유할 때
• 외부 오픈소스를 직접 수정해야 할 때
• 라이브러리 버전을 정확히 고정해야 할 때
• 모노레포가 아닌 독립 저장소 구조를 유지하고 싶을 때

 

예제 🐧 colors-helper-tools를 Submodule로 추가하기

이번 예제에서는 colors-helper-tools 저장소를 Submodule로 추가해보자

1. 프로젝트 생성

mkdir my-app
cd my-app
git init

 

2. Submodule 추가

git submodule add https://github.com//colors-helper-tools.git libs/colors-helper-tools

실제 GitHub 저장소 URL을 사용해야 한다.

이 명령을 실행하면...

• libs/colors-helper-tools 디렉토리가 생성되고
• .gitmodules 파일이 추가된다

 

.gitmodules 예시

[submodule "libs/colors-helper-tools"]
  path = libs/colors-helper-tools
  url = https://github.com//colors-helper-tools.git

이 파일은 “어디에서 이 서브모듈을 가져오는지”를 정의한다.

 

3. 커밋

git add .
git commit -m "Add colors-helper-tools as submodule"

 

중요한 점은

👉 상위 저장소는 서브모듈의 특정 커밋 SHA를 기록한다
👉 실제 코드는 서브모듈 저장소에 존재한다

+ Submodule을 `add` 했다고 해서 항상 연결이 완벽한 건 아니다.  

추가로 “포인터(gitlink)가 상위 저장소 인덱스에 제대로 기록됐는지” 확인하는 과정이 꼭 필요하다.

예를 들어 아래처럼 점검하면 안전하다.

# 1) 서브모듈 상태 확인 (커밋 SHA가 보여야 정상)
git submodule status

# 2) 상위 저장소 인덱스에 gitlink(160000)로 잡혔는지 확인
git ls-files --stage vendor/colors-helper-tools

정상이라면 `git ls-files --stage` 결과에서 앞에 `160000` 모드가 보인다.  
이 값은 “일반 파일”이 아니라 “서브모듈 포인터”로 기록됐다는 뜻이다.

👉 즉, `git submodule add` 후에는  
- `.gitmodules`가 생겼는지  
- `git submodule status`에 SHA가 보이는지  
- `git ls-files --stage`에서 `160000`이 잡히는지  
이 3가지를 확인하면 실수를 크게 줄일 수 있다.  

`submodule`은 강력하지만, 이런 작은 체크가 안정성을 만든다.

 

Submodule 포함 프로젝트를 클론하는 방법

Submodule이 포함된 저장소를 클론할 때는 일반 clone으로는 부족하다.

방법 1 ➡️ 한 번에 받기

git clone --recurse-submodules <repo-url>

방법 2 ➡️ 이미 클론했다면

git submodule init
git submodule update

 

 

Submodule 업데이트하기

서브모듈 최신 커밋으로 갱신하기

cd libs/colors-helper-tools
git pull origin main
cd ../..
git add libs/colors-helper-tools
git commit -m "Update submodule"

여기서 중요한 점은..../

• 서브모듈 내부에서 pull
• 상위 저장소에서 커밋

Submodule은 두 단계 커밋 구조라는 걸 기억하자.

 

⭐ Submodule의 장점

1. 독립 버전 관리

각 저장소가 완전히 분리되어 관리된다.

2. 정확한 버전 고정

특정 커밋을 가리키므로 재현성이 높다.

3. 외부 프로젝트 포함에 적합

Fork한 오픈소스를 프로젝트 내부에 안정적으로 연결 가능.

 

☀️ Submodule의 단점

1. 협업 시 실수하기 쉬움

submodule update를 안 하면 디렉토리가 비어있다

2. 커밋 구조가 직관적이지 않음

초보자에게는 헷갈린다

3. CI/CD 설정이 조금 번거롭다

recurse-submodules 옵션 필요 

 

Submodule vs npm 설치

그럼 이런 질문이 생긴다.

npm install 하면 되는데 왜 submodule을 쓰나?

차이점은 다음과 같다.

• npm → 패키지 배포 기반 의존성
• submodule → Git 저장소 기반 연결

즉,

• 수정 가능한 상태로 직접 관리하고 싶다면 submodule
• 일반적인 의존성이라면 npm

 

요약하자면.... 👑

Git Submodule은

• 강력하지만
• 약간 까다로운 기능이다.

공통 라이브러리 관리, 외부 저장소 포함, 버전 고정이 필요하다면 여전히 매우 유용한 도구다.

핵심은 다음과 같다.

Submodule은 “코드 복사”가 아니라
“저장소 포인터를 연결하는 것”이다.

 

 

참고자료 📎

• Git 공식 문서 — Submodules
  https://git-scm.com/docs/git-submodule
• Pro Git Book — Submodules
  https://git-scm.com/book/en/v2/Git-Tools-Submodules
• Atlassian Git Tutorial — Submodules
  https://www.atlassian.com/git/tutorials/git-submodule

 

🤩 실제로 작업해본 내용은 다음 PR에서 확인할 수 있습니다!

https://github.com/citron03/frontend-stack-playground/pull/13

feat(git): git submodule setting and example web by citron03 · Pull Request #13 · citron03/frontend-stack-playground