Git Submodule에 대해 알아보자

Git Submodule이란?

• 하나의 Git 저장소 안에 다른 Git 저장소를 하위 디렉토리로 포함시켜 관리하는 기능임
• 메인 프로젝트에서 공통 라이브러리나 외부 모듈을 독립적으로 관리하고 싶을 때 사용함

왜 쓰는가?

• 공통 코드 관리: 여러 프로젝트에서 똑같이 사용하는 모듈이 있을 때, 매번 복사해서 붙여넣는 대신 서브모듈로 등록해서 코드 중복을 피할 수 있음
• 독립적인 버전 관리: 서브모듈은 특정 커밋 해시를 가리킴. 서브모듈 원격 저장소에 새로운 커밋이 올라가도 메인 프로젝트가 자동으로 영향을 받지 않음. 원하는 시점에 직접 업데이트를 결정할 수 있어 안전함
• 권한 분리: 메인 프로젝트 개발자와 서브모듈 개발자의 접근 권한을 다르게 설정할 수 있음

핵심 명령어 정리

1. 서브모듈 추가하기

git submodule add <서브모듈_저장소_URL> <로컬_디렉토리_경로>

• 명령어를 실행하면 메인 저장소 루트에 .gitmodules 파일이 생성됨
• 해당 파일에 서브모듈의 경로와 URL 정보가 기록되며, 메인 프로젝트는 서브모듈의 특정 커밋 해시를 가리키게 됨

2. 서브모듈이 포함된 프로젝트 클론하기

• 단순히 git clone <메인_저장소_URL>만 하면 서브모듈 디렉토리는 빈 폴더로만 나타남
• 서브모듈의 실제 소스코드까지 정상적으로 가져오려면 아래 두 가지 방법 중 하나를 선택해야 함

방법 A: 클론할 때 한 번에 가져오기

git clone --recursive <메인_저장소_URL>

방법 B: 이미 메인 프로젝트를 클론한 상태에서 가져오기

git submodule init
git submodule update
# 또는 한 줄로 해결
git submodule update --init --recursive

3. 서브모듈 업데이트하기

• 서브모듈 원격 저장소의 최신 커밋을 가져와서 업데이트하고 싶을 때 사용함

git submodule update --remote

4. 서브모듈 변경사항 저장하고 푸시하기

• 서브모듈 디렉토리 내부에서 코드를 직접 수정한 경우의 프로세스임

1. 서브모듈 디렉토리로 이동하여 변경사항을 커밋하고 서브모듈 원격 저장소에 푸시함
2. 메인 프로젝트 디렉토리로 돌아와서 서브모듈의 변경된 커밋 해시 상태를 확인하고 메인 프로젝트 저장소에도 커밋 및 푸시를 진행함

• 메인 저장소에만 푸시하고 서브모듈 푸시를 깜빡하면 다른 팀원들이 코드를 당겨올 때 에러가 발생하므로 주의해야 함

주의할 점과 단점

• 커밋 해시 기반 관리: 메인 프로젝트는 서브모듈 내부 파일의 세부 변경 사항을 직접 관리하지 않고 특정 '커밋 해시'만 기록함. 이 구조를 이해하지 못하면 협업할 때 꼬이기 쉬움
• 싱크 맞추기 귀찮음: 팀원이 서브모듈 업데이트를 푸시한 경우, 다른 팀원들은 단순히 git pull만 해서는 안 되고 git submodule update를 추가로 실행해 주어야 함. 주기적으로 명령어를 쳐야 해서 번거로움
• 히스토리 추적의 한계: 메인 프로젝트 커밋 로그만 봐서는 서브모듈 내부에서 정확히 어떤 코드가 어떻게 바뀌었는지 파악하기 어려움

한 줄 요약

• 여러 프로젝트에서 공통으로 쓰는 핵심 모듈을 분리해서 깔끔하게 관리하고 싶다면 귀찮음을 감수하고 도입할 가치가 충분함. 단, 협업 시 팀원들과 서브모듈 동기화 규칙을 확실히 정해두어야 삽질을 막을 수 있음