Git Submodule 충돌 및 동기화 에러 완벽 해결: 모노레포 아키텍처

9월 29, 2026

[Troubleshooting] Git Submodule 충돌 및 동기화 에러 완벽 해결: 모노레포 아키텍처

"사내 공통 라이브러리를 Git Submodule로 분리하여 메인 프로젝트에 연결했습니다. 그런데 다른 팀원이 메인 프로젝트를 git pull 받았더니 서브모듈 폴더가 텅 비어있거나, 커밋이 엉뚱한 과거 시점을 가리키며 빌드가 박살 났습니다."

마이크로서비스 아키텍처(MSA)나 모노레포(Monorepo)를 지향하며 프로젝트를 분리하기 시작한 개발 조직이 100% 마주하는 '버전 동기화의 지옥'입니다. 서치 콘솔에 'Git Submodule 에러'를 검색하면 수백 개의 파편화된 명령어들이 쏟아지지만, 근본적인 원인을 모른 채 타이핑만 하면 레포지토리는 되돌릴 수 없는 스파게티가 됩니다.

Git Submodule은 일반적인 폴더가 아닙니다. '특정 시점의 시간(Commit Hash)을 가리키는 포인터'입니다. 초보자들은 메인 프로젝트를 당겨오면 서브모듈도 알아서 최신 코드로 업데이트될 것이라 착각합니다. 본 가이드에서는 이 시공간의 단절을 해체하고, 서브모듈의 동기화 누락을 원천 차단하는 Git 환경 자동화 아키텍처를 단호하게 제시합니다.

📌 이 글의 핵심 포인트

시공간의 분리: 메인 레포지토리는 서브모듈의 파일이 아니라 특정 커밋 해시(Commit Hash)만을 기억한다는 본질 이해

빈 폴더 에러 해결: git clone 시 누락되는 서브모듈 데이터를 update --init으로 강제 맵핑하는 법

워크플로우 자동화: submodule.recurse 글로벌 설정을 통한 휴먼 에러 방어 구축

1단계: 핵심 원인 분석 - 포인터와 Detached HEAD

메인 프로젝트에서 서브모듈 폴더 안으로 들어가 git status를 쳐보면 HEAD detached at 1a2b3c4라는 메시지가 뜹니다. 이는 에러가 아닙니다.

메인 프로젝트는 서브모듈이 main 브랜치의 최신 코드를 가지든 말든 관심이 없습니다. 오직 "내가 이 메인 프로젝트를 커밋했을 당시, 저 서브모듈은 1a2b3c4라는 커밋 상태였어"라는 스냅샷(Snapshot)만을 기록합니다. 따라서 다른 팀원이 메인 프로젝트를 Pull 받았을 때, 서브모듈 폴더 안의 코드는 자동으로 최신화되지 않고 과거의 특정 시점에 멈춰있게 되며 충돌이 발생하는 것입니다.

2단계: 완벽한 트러블슈팅 - 수동 동기화의 정석

프로젝트를 처음 클론(Clone)했거나, 누군가 서브모듈의 버전을 업데이트한 메인 코드를 Pull 받았다면 반드시 아래의 명령어로 서브모듈의 시공간을 동기화해야 합니다.


# ❌ 일반적인 clone은 서브모듈 폴더를 빈 껍데기로 가져옵니다.
git clone https://github.com/my-org/main-repo.git

# ✅ 1. Clone할 때 처음부터 서브모듈까지 전부 가져오는 완벽한 방법
git clone --recurse-submodules https://github.com/my-org/main-repo.git

# ✅ 2. 이미 Clone을 받았는데 서브모듈이 비어있거나 버전이 꼬였을 때 복구하는 명령
git submodule update --init --recursive

위의 업데이트 명령을 실행하면, Git은 메인 프로젝트가 기억하고 있는 서브모듈의 정확한 커밋 해시를 찾아 코드를 완벽하게 조립해 냅니다.

3단계: 엔터프라이즈 아키텍처 - 휴먼 에러를 막는 자동화

매번 --recurse-submodules 옵션을 치거나 업데이트 명령어를 입력하는 것은 개발자의 피로도를 높입니다. 진정한 아키텍트라면 개인의 기억력에 의존하지 않고 시스템 레벨에서 이를 강제해야 합니다.

터미널에 아래의 Git 글로벌 환경 설정을 입력하십시오.


# 메인 프로젝트를 조작(checkout, pull 등)할 때 서브모듈도 알아서 따라오도록 전역 설정 강제
git config --global submodule.recurse true

이 명령어 한 줄을 세팅하는 순간, 개발자가 무심코 git pull이나 git checkout을 치더라도 Git 엔진이 백그라운드에서 서브모듈까지 완벽하게 동기화시킵니다. 버전 불일치로 인한 빌드 에러는 영원히 소멸됩니다.

🙋‍♂️ 자주 묻는 질문 (FAQ)

Q. 서브모듈 폴더 안에서 코드를 수정하고 푸시(Push)해도 되나요?
A. 가능하지만 권장하지 않습니다. 서브모듈 내부에서 코드를 변경하고 커밋한 뒤, 메인 프로젝트에서도 바뀐 서브모듈의 해시를 다시 커밋해야 하는 '2중 커밋' 작업을 완벽히 수행해야 합니다. 서브모듈 코드는 별도의 레포지토리 창을 열어 독립적으로 수정 및 푸시하는 것이 안전합니다.

💡 핵심 정리 및 마무리

Git Submodule은 마이크로서비스 생태계에서 코드의 재사용성을 극대화하는 강력한 무기지만, 시공간의 종속성을 통제하지 못하면 팀 전체의 생산성을 갉아먹는 폭탄이 됩니다. 포인터(Pointer)의 본질을 명확히 이해하고, 글로벌 자동화 설정을 통해 동기화 누락을 원천 차단하는 무결점 버전 관리 워크플로우를 완성하십시오.

이 블로그 검색

HAGOCUBE | 디지털 생산성 아키텍트