여러 프로젝트에서 공통으로 사용하는 모듈이 있거나, 특정 버전의 외부 라이브러리를 내 프로젝트에 포함시켜야 할 때 어떻게 관리하고 계신가요? 코드를 직접 복사하여 붙여넣는 방식은 원본의 변경사항을 추적하기 어렵다는 단점이 있습니다.
오늘은 바로 이 문제를 해결하기 위한 Git의 강력한 기능, git submodule 에 대해 소개해 드리고자 합니다. git submodule은 하나의 Git 저장소 안에 다른 Git 저장소를 독립적으로 포함시키는 기능입니다.
Git Submodule 핵심 명령어#
먼저 서브모듈을 다룰 때 사용하는 필수 명령어들을 알아보겠습니다.
서브모듈 추가하기 (git submodule add)#
내 프로젝트에 외부 저장소를 서브모듈로 추가합니다.
git submodule add [저장소_URL] [내_프로젝트에서의_경로]
이 명령을 실행하면, .gitmodules 파일이 생성 또는 업데이트되어 서브모듈 정보가 기록되고, 지정한 경로에 해당 저장소가 복제(clone)됩니다. 이 변경사항들을 부모 프로젝트에 커밋해야 서브모듈 추가가 최종적으로 완료됩니다.
서브모듈이 포함된 프로젝트 복제하기 (git clone)#
서브모듈이 포함된 프로젝트를 처음 받아올 때 사용합니다.
방법 A (가장 추천): clone 시점에 서브모듈까지 한 번에 초기화하고 데이터를 받아옵니다.
git clone --recurse-submodules [부모_저장소_URL]
방법 B (이미 clone 한 경우): 이미 clone을 받은 상태라면, 아래 명령어로 서브모듈을 초기화하고 데이터를 받아올 수 있습니다.
git submodule update --init --recursive
서브모듈 업데이트하기 (git submodule update)#
서브모듈의 원격 저장소에 새로운 변경사항이 생겼을 때, 내 프로젝트에 이를 반영합니다.
아래 명령어로 서브모듈을 원격 저장소의 최신 상태로 업데이트합니다.
git submodule update --remote
부모 프로젝트에서 git status를 실행해 보면, 서브모듈이 가리키는 커밋이 변경되었다는 내용이 나타납니다. 이 변경된 커밋 정보를 부모 프로젝트에 기록하기 위해 커밋을 진행합니다.
git add [서브모듈_경로]
git commit -m "Updated submodule to the latest version"
서브모듈 제거하기 (git submodule deinit & rm)#
먼저 서브모듈을 비활성화하고 관련 설정을 삭제합니다.
git submodule deinit -f [서브모듈_경로]
서브모듈 디렉토리와 .gitmodules 파일의 관련 내용을 완전히 삭제합니다.
git rm -f [서브모듈_경로]
이 변경사항을 부모 프로젝트에 커밋합니다.
git commit -m "Removed submodule"
프로젝트에 활용하기#
Python 패키지 이름 변경하여 사용하기#
팀에서 공통으로 사용하는 유틸리티 라이브러리(common-utils)가 있지만, 저장소 이름에 대시(-)가 포함되어 파이썬에서 import 할 수 없는 경우가 있습니다. 이때 서브모듈을 추가하면서 경로 이름을 지정하여 이 문제를 해결할 수 있습니다.
# 저장소 이름은 'common-utils'이지만,
# 우리 프로젝트에는 'common_utils'라는 디렉토리로 추가합니다.
git submodule add https://github.com/your-org/common-utils.git common_utils
이제 파이썬 코드에서 import common_utils와 같이 하이픈 없는 이름으로 라이브러리를 사용할 수 있습니다.
Hugo 블로그에 테마 적용하기#
정적 사이트 생성기인 Hugo는 테마를 서브모듈로 관리하는 것을 권장합니다. 이렇게 하면 테마의 원본은 그대로 유지하면서, 내 블로그에서는 특정 버전의 테마를 고정하여 안정적으로 사용할 수 있습니다.
# 내 Hugo 블로그 프로젝트의 themes 디렉토리 안에
# blowfish 테마를 서브모듈로 추가합니다.
git submodule add https://github.com/nunocoracao/blowfish.git themes/blowfish
테마가 업데이트되면 git submodule update --remote 명령으로 쉽게 최신 버전을 적용할 수 있어 관리가 매우 편리해집니다.
공통 API 문서(Swagger/OpenAPI) 관리하기#
여러 마이크로서비스 프로젝트가 공통의 API 명세를 참조해야 할 때, API 명세만을 관리하는 별도의 Git 저장소를 만들고 각 프로젝트에서 이를 서브모듈로 가져와 사용할 수 있습니다.
# 주문 서비스 프로젝트에 공통 API 명세 저장소를 추가합니다.
git submodule add https://github.com/your-org/api-specs.git api-docs
이를 통해 모든 서비스가 항상 동일한 버전의 API 문서를 참조하게 되어 일관성을 유지할 수 있습니다.
특정 버전의 외부 라이브러리 고정하기#
프로젝트가 특정 버전의 외부 라이브러리에 강하게 의존하고 있을 때, 서브모듈을 사용하여 해당 라이브러리의 특정 커밋 버전을 프로젝트에 고정시킬 수 있습니다.
# 특정 그래픽 라이브러리의 최신 버전은 버그가 있어,
# 안정적인 v1.2.3 태그 버전을 사용하려고 합니다.
# 1. 먼저 서브모듈을 추가합니다.
git submodule add https://github.com/some-vendor/graphic-lib.git libs/graphic-lib
# 2. 서브모듈 디렉토리로 이동하여 원하는 태그로 체크아웃합니다.
cd libs/graphic-lib
git checkout v1.2.3
# 3. 부모 프로젝트로 돌아와 변경된 커밋 정보를 저장합니다.
cd ../..
git add libs/graphic-lib
git commit -m "Pin graphic-lib to version v1.2.3"
이제 이 프로젝트를 사용하는 모든 팀원은 정확히 v1.2.3 버전의 라이브러리를 사용하게 되어, 버전 불일치로 인한 문제를 원천적으로 예방할 수 있습니다.
마무리하며#
Git Submodule은 외부 종속성을 체계적으로 관리하고, 여러 프로젝트 간의 코드 재사용성을 높이는 강력한 도구입니다. 처음에는 개념이 다소 생소할 수 있지만, 위 예시들을 참고하여 프로젝트에 적용해 보시면 그 편리함과 안정성을 분명히 체감하실 수 있을 것입니다.
참조
- Git 공식 문서 - Submodules: https://git-scm.com/book/en/v2/Git-Tools-Submodules