Git Submodule 알아보기

git submodule 이란 무엇일까?

git submodule은 Git 저장소 안에 또 다른 Git 저장소를 포함시키는 기능입니다. 마치 폴더 안에 폴더를 넣는 것과 비슷하지만, 단순히 파일을 복사하는 것이 아니라 독립적인 Git 저장소를 특정 커밋 시점으로 연결하는 방식입니다.

 

핵심 개념

• 독립적인 저장소 안의 저장소: 메인 프로젝트 저장소는 서브모듈 저장소를 특정 커밋으로 "참조"만 합니다. 서브모듈 저장소는 자체적인 커밋 히스토리, 브랜치 등을 완전히 독립적으로 가집니다.
• 특정 커밋 시점 고정: 메인 프로젝트는 서브모듈의 특정 커밋 ID를 기록합니다. 즉, 서브모듈은 특정 시점의 버전으로 고정되어 메인 프로젝트의 빌드 안정성을 확보할 수 있습니다.
• 코드 재사용 및 모듈화: 공통으로 사용되는 라이브러리, 컴포넌트 등을 서브모듈로 분리하여 여러 프로젝트에서 재사용하고, 프로젝트를 기능별 모듈로 구성하여 관리 효율성을 높입니다.

 

왜 git submodule을 사용해야 할까?

git submodule을 사용하면 다음과 같은 실질적인 이점을 얻을 수 있습니다:

 

코드 재사용성 극대화

• 공통 라이브러리/모듈 재사용: 여러 프로젝트에서 공통으로 사용하는 라이브러리, 디자인 시스템, 유틸리티 모듈 등을 서브모듈로 만들어 코드 중복을 줄이고 유지보수 효율성을 높입니다.
• Vendor 코드 관리: 외부 Vendor에서 제공받은 코드를 서브모듈로 관리하여 프로젝트 저장소를 깔끔하게 유지하고, Vendor 코드 변경 이력을 추적하기 용이합니다.

 

프로젝트 모듈화 및 관리 효율성 향상

• 대규모 프로젝트 분할 관리: 거대한 프로젝트를 기능별, 팀별 모듈로 분리하여 개발 및 유지보수 복잡성을 낮춥니다. 각 모듈은 독립적으로 개발하고 버전 관리하며, 필요한 경우 메인 프로젝트에 통합합니다.
• 독립적인 개발 환경 유지: 서브모듈은 독립적인 저장소이므로, 각 모듈 개발자는 메인 프로젝트의 영향을 최소화하면서 독립적인 개발 환경을 유지할 수 있습니다.

 

버전 관리 및 빌드 안정성 확보

• 특정 버전 Submodule 고정: 메인 프로젝트는 서브모듈의 특정 커밋 시점을 참조하므로, 서브모듈의 예기치 않은 변경으로 인한 빌드 실패 위험을 줄여 안정적인 빌드 환경을 구축할 수 있습니다.
• 의존성 버전 명시적 관리: 프로젝트 의존성을 서브모듈을 통해 명시적으로 관리하여 프로젝트의 의존성 관리를 더욱 투명하고 예측 가능하게 만듭니다.

 

협업 효율성 증대

• 팀별 모듈 개발: 대규모 팀 프로젝트에서 각 팀은 특정 서브모듈을 독립적으로 개발하고, 메인 프로젝트는 각 팀의 결과물을 통합하는 방식으로 협업 효율성을 높일 수 있습니다.
• 외부 협력사 코드 통합: 외부 협력사에서 개발한 모듈을 서브모듈 형태로 프로젝트에 통합하여 효율적인 협업 환경을 구축할 수 있습니다.

 

git submodule 사용 방법

git submodule 사용법은 크게 추가, 초기화/업데이트, 변경사항 관리 세 단계로 나눌 수 있습니다. 각 단계별 명령어와 함께 자세히 알아보겠습니다.

 

Submodule 추가

서브모듈을 추가하려면 git submodule add 명령어를 사용합니다.

git submodule add <서브모듈_저장소_URL> <서브모듈_경로>

• 서브모듈 저장소 URL: 추가하려는 서브모듈의 Git 저장소 URL (HTTPS 또는 SSH).
• 서브모듈 경로: 메인 프로젝트에서 서브모듈을 위치시킬 경로 (디렉토리 이름).

 

예시: module-rest 라는 서브모듈을 프로젝트 루트 디렉토리 아래에 추가하는 경우

git submodule add https://github.com/your-org/module-rest.git module-rest

 

명령어 실행 결과:

• .gitmodules 파일 생성 또는 수정: 서브모듈 설정 정보 (url, path) 가 .gitmodules 파일에 기록됩니다.
• 서브모듈 디렉토리 생성: <서브모듈_경로> 에 지정한 이름의 디렉토리 (module-rest) 가 생성됩니다. 하지만, 아직 서브모듈 저장소의 파일들은 다운로드되지 않은 빈 디렉토리 상태입니다.
• 서브모듈이 스테이징 영역에 추가: .gitmodules 파일과 서브모듈 디렉토리 (빈 디렉토리) 가 스테이징 영역에 추가됩니다.

 

주의: git submodule add 명령어 실행 후에는 반드시 변경사항을 커밋해야 합니다.

git commit -m "Add module-rest submodule"

 

Submodule 초기화 및 업데이트

서브모듈을 추가한 후, 또는 다른 사람이 서브모듈이 포함된 프로젝트를 Clone한 후에는 서브모듈을 초기화하고 업데이트해야 서브모듈 저장소의 파일들을 가져올 수 있습니다.

초기화 (Initializing): .gitmodules 파일에 정의된 서브모듈을 초기화합니다. 서브모듈 설정을 .git/config 에 등록하고, 서브모듈 디렉토리를 생성합니다. (이미 생성되어 있다면 생략)

git submodule init

 

업데이트 (Updating): 서브모듈 저장소에서 파일을 다운로드하고, .gitmodules 에 명시된 커밋 시점으로 서브모듈을 체크아웃합니다.

git submodule update --init --recursive

• --init: 서브모듈이 초기화되지 않은 경우, 초기화 단계를 함께 수행합니다.
• --recursive: 서브모듈 안에 또 다른 서브모듈 (nested submodule) 이 있는 경우, 중첩된 서브모듈까지 모두 초기화하고 업데이트합니다.

 

일반적인 초기화 및 업데이트 명령어 (한 번에 실행):

git submodule update --init --recursive

 

명령어 실행 결과:

• 서브모듈 디렉토리 (module-rest) 에 서브모듈 저장소의 파일들이 다운로드됩니다.
• 서브모듈은 .gitmodules 에 명시된 특정 커밋 시점으로 체크아웃됩니다.

팁: 프로젝트를 처음 Clone한 후에는 항상 git submodule update --init --recursive 명령어를 실행하여 서브모듈을 초기화하고 업데이트하는 것을 잊지 마세요.

 

Submodule 변경 사항 관리

서브모듈은 독립적인 Git 저장소이므로, 서브모듈 내부에서 변경 사항을 만들고 커밋/푸시하는 것은 일반적인 Git 워크플로우와 동일합니다. 하지만, 메인 프로젝트에서 서브모듈 변경 사항을 어떻게 관리해야 하는지 주의해야 합니다.

 

서브모듈 내부 변경

1. 서브모듈 디렉토리 (module-rest) 로 이동합니다.

2. 서브모듈 내부에서 파일을 수정하고, 변경 사항을 스테이징하고 커밋합니다.

   cd module-rest
   # ... 파일 수정 ...
   git add .
   git commit -m "Fix bug in module-rest"
   

3. (선택 사항) 서브모듈 변경 사항을 서브모듈 원격 저장소에 푸시합니다.

   git push origin main # 또는 사용하는 브랜치
   

4. 메인 프로젝트 디렉토리로 다시 이동합니다. (cd ..)

5. 메인 프로젝트에서 서브모듈 변경 사항을 업데이트하고, 커밋합니다.

   git add module-rest # 변경된 서브모듈 커밋 ID 스테이징
   git commit -m "Update module-rest submodule to latest commit"
   

 

메인 프로젝트에서 Submodule 버전 업데이트

1. 서브모듈 디렉토리 (module-rest) 로 이동합니다.

2. 서브모듈 저장소에서 최신 변경 사항을 가져옵니다.

   cd module-rest
   git pull origin main # 또는 사용하는 브랜치
   

3. 메인 프로젝트 디렉토리로 다시 이동합니다. (cd ..)

4. 메인 프로젝트에서 서브모듈 변경 사항을 업데이트하고, 커밋합니다. (위와 동일한 명령어)

   git add module-rest # 변경된 서브모듈 커밋 ID 스테이징
   git commit -m "Update module-rest submodule to latest commit"
   

 

핵심: 메인 프로젝트는 서브모듈의 특정 커밋 ID를 참조하므로, 서브모듈 내부 또는 외부에서 서브모듈이 변경되면 메인 프로젝트에서 반드시 서브모듈을 업데이트하고 커밋해야 변경 사항이 메인 프로젝트에 반영됩니다.

 

git submodule 주의사항

• 서브모듈 업데이트 주의: git clone 후 git submodule update --init --recursive를 실행해야 서브모듈이 정상적으로 가져와집니다.
• 변경사항 커밋 주의: 서브모듈 내 변경 사항을 상위 저장소에 커밋하려면 서브모듈에서도 별도로 커밋 후 상위 저장소에서 반영해야 합니다.
• 브랜치 관리 문제: 서브모듈은 특정 커밋을 가리키므로 기본적으로 브랜치를 따라가지 않습니다. 최신 상태 유지하려면 git submodule update --remote가 필요합니다.
• 삭제 시 주의사항: 단순히 rm -rf로 삭제하면 .gitmodules에도 잔여 정보가 남습니다. git submodule deinit -f와 git rm을 사용해야 완전히 제거됩니다.
• 충돌 발생 가능성: 여러 개발자가 서브모듈을 개별적으로 업데이트하면 충돌이 발생할 수 있습니다. 이를 방지하려면 서브모듈 변경 시 명확한 커밋 및 동기화가 필요합니다.
• CI/CD에서의 문제: CI/CD에서 서브모듈을 사용하는 경우 git submodule update --init --recursive를 빌드 스크립트에 포함해야 정상적으로 동작합니다.

 

참고 자료

• Git 공식 문서 - Submodules
• Atlassian Git Tutorial - Submodules

#Git #Submodule #버전관리 #코드재사용 #프로젝트관리 #개발팁 #GitSubmodule #Submodules #GitWorkflow #개발효율 #협업