gitmodules

.gitmodules

Git 프로젝트에서 다른 Git 저장소를 포함하는 서브모듈 기능은, 외부 라이브러리나 독립 모듈을 별도의 이력으로 관리하면서도 상위 프로젝트와 연동할 수 있도록 도와줍니다. 이때, .gitmodules 파일은 서브모듈의 경로, 원격 저장소 URL, 그리고 (옵션으로) 추적할 브랜치 등 정보를 설정해 두는 중요한 메타데이터 파일입니다.

---

기본 구성

서브모듈을 추가하면 Git은 자동으로 .gitmodules 파일을 생성합니다. 기본적인 구성은 아래와 같습니다.

[submodule "libs/somelib"]
    path = libs/somelib
    url = https://github.com/user/somelib.git

• 섹션 이름: [submodule "libs/somelib"]는 서브모듈 이름이나 경로를 식별하기 위한 라벨입니다. 사용자 임의로 정할 수 있지만, 보통 서브모듈이 위치하는 경로를 반영합니다.

• path: 실제 서브모듈이 체크아웃 될 로컬 경로를 지정합니다.

• url: 서브모듈의 원격 저장소 주소를 나타내며, 이 URL을 통해 Git은 해당 저장소를 클론하거나 업데이트합니다.

또한, 선택 사항으로 특정 브랜치를 추적하도록 지정할 수도 있습니다.

[submodule "libs/somelib"]
    path = libs/somelib
    url = https://github.com/user/somelib.git
    branch = main

이렇게 하면 git submodule update --remote 명령어를 사용할 때, 지정한 브랜치의 최신 커밋으로 서브모듈이 업데이트됩니다.

---

서브모듈 변경 사항

서브모듈 내부에서 파일 수정 후 커밋, 푸시를 진행하면 해당 서브모듈 저장소는 최신 상태로 갱신됩니다. 그러나 상위(메인) 저장소는 서브모듈의 커밋 포인터만을 기록하기 때문에, 내부 변경 사항이 반영된 새 커밋 해시로 업데이트되지 않습니다. 즉, 서브모듈 변경 후 상위 저장소에 해당 디렉토리를 다시 add 및 커밋해야, 다른 협업자들도 최신 상태의 서브모듈을 받을 수 있습니다.

예를 들어, 서브모듈 내에서 업데이트 후 상위 저장소에서 반영하는 절차는 다음과 같습니다.

# 서브모듈 내부 변경 사항을 commit & push
cd libs/somelib
git add .
git commit -m "서브모듈에 새로운 기능 추가"
git push origin main

# 상위 저장소로 돌아와 서브모듈 포인터 업데이트 반영
cd ..
git add libs/somelib
git commit -m "Update submodule libs/somelib pointer to latest commit"
git push origin main

또한, 상위 저장소에서 git submodule update --remote 명령어를 사용하면 .gitmodules에 지정한 브랜치를 기준으로 서브모듈을 일괄 업데이트할 수 있습니다.

---

팁

• 통일된 서브모듈 정보 공유: .gitmodules 파일은 상위 저장소에 포함되므로, 모든 팀원이 동일한 서브모듈 경로와 URL을 사용하게 됩니다. 이를 통해 각자 다른 버전을 사용하거나 경로를 잘못 지정하는 문제를 예방할 수 있습니다.

• 서브모듈 변경 시 주의: 서브모듈의 업데이트는 단순히 내부 변경 사항 반영뿐만 아니라, 상위 저장소의 커밋 포인터 변경까지 필요합니다. 따라서, 서브모듈 업데이트 후 반드시 상위 저장소에 변경 사항을 커밋하여 동기화를 맞춰야 합니다.

• 서브모듈 삭제/이동: 서브모듈을 제거하거나 다른 위치로 이동할 때는 .gitmodules 파일뿐 아니라, Git 내부 캐시(.git/config 내 서브모듈 관련 설정)까지 정리해야 하므로 주의가 필요합니다.

---

.gitmodules 파일은 Git 서브모듈 관리의 핵심 구성 요소로, 외부 저장소와 상위 프로젝트를 연결하는 역할을 합니다. 이 파일에 올바른 경로와 URL, 선택적으로 추적할 브랜치를 지정해두면, 프로젝트를 클론하거나 업데이트할 때 서브모듈의 상태를 손쉽게 동기화할 수 있습니다. 서브모듈 관리에 익숙해지면, 대규모 프로젝트에서 공용 모듈이나 외부 라이브러리의 버전 관리가 더욱 명확해지고, 협업 과정에서의 혼란을 줄일 수 있습니다.