Git Submodule이란?

Git Submodule은 다른 Git 저장소를 내 저장소 안에 특정 커밋에 고정해서 포함하는 기능이에요.

왜 쓰는가

외부 라이브러리 소스코드가 필요할 때 직접 복사해서 넣으면 이런 문제가 생겨요.

• 원본 저장소와의 연결이 끊겨요
• 업데이트를 추적할 수 없어요
• 같은 코드가 여러 곳에 생겨요

Submodule을 쓰면 "이 저장소의 이 커밋을 여기에 넣어라"는 참조(포인터) 만 저장해요.

실제로 저장되는 것

• .gitmodules — submodule URL과 경로 매핑
• Git 내부에 해당 submodule이 가리키는 커밋 해시

내 저장소에는 전체 소스 대신 어떤 커밋을 참조하는지만 기록돼요.

사용법

추가

git submodule add https://github.com/example/lib.git path/to/lib

Clone

# clone할 때 submodule까지 한번에
git clone --recurse-submodules <repo-url>

# 이미 clone한 후 submodule을 가져오기
git submodule update --init --recursive

업데이트

submodule을 최신 커밋으로 올리고 싶을 때는 이렇게 해요.

cd path/to/lib
git pull origin main
cd ..
git add path/to/lib
git commit -m "update submodule"

git submodule update --remote path/to/lib로 원격 브랜치의 최신 커밋을 한 번에 가져올 수도 있어요. 이때도 바뀐 커밋을 git add와 git commit으로 기록해야 해요.

주의할 점

• 그냥 git clone하면 submodule 디렉토리가 비어 있어요. --recurse-submodules 옵션을 쓰거나, clone한 뒤 git submodule update --init --recursive를 실행해야 해요.
• submodule은 특정 커밋에 고정되어 있어서, 원본 저장소가 업데이트되어도 자동으로 따라가지 않아요. 직접 업데이트해야 해요.