Github submodule 사용하기

😵 들어가며

---

프로젝트에서 공통 레포를 사용할 일이 있었다. 나같은 경우엔 예약 모듈과 프로모션 페이지를 개발해야했었고 그 내부에서 동일한 형태의 예약 폼을 사용해야했다. 토시하나 틀리지않은 예약 폼이였기에 하나의 레포지토리로 관리하고 각각의 프로젝트에서 끌여다쓴다면 예약폼을 수정해도 각각의 레포를 돌아다니며 수정하지 않아도 되고 그냥 풀받으면 되겠다는 생각에 방법을 찾았다. 역시나 방법은 있었고 서브모듈이라는 개념을 도입해보았다.

그래서 오늘은 서브모듈에 대한 개념, 필요성, 주의점 등에 관해 사용기를 풀어보려한다.

😀 본문

---

1. 서브모듈이란?

   • 하나의 Git 저장소 안에 다른 Git 저장소를 하위 디렉터리로 포함시키는 기능
   • 공통 UI 모듈, 라이브러리, 디자인 시스템 등 재사용 가능한 코드 공유
   • 여러개의 프로젝트에서 동일한 코드를 쓰며 복붙하는 방식보다 유지보수가 훨씬 효율적

   
   

2. 서브모듈 설치법

   • 서브모듈 추가 : git submodule add <레포지토리 주소> <경로>

     or

   • 새로 클론한 프로젝트(서브모듈이 있는 프로젝트)에서 서브모듈도 같이 가져올 때 : git clone --recurse-submodules <레포지토리 주소>

   .gitmodules 파일이 자동 생성되여 커밋해주면 된다.

   
   

3. 서브모듈 사용 시 주의점

   3-1. 경로 문제 (Alias 불가)

   • 서브모듈 내 코드에서 @/components/... 이런 alias를 쓰면 외부에서 해석되지 않음

   • 메인 프로젝트의 tsconfig.json 또는 vite.config.js, webpack.config.js에서 경로 alias 설정이 서브모듈 코드에 영향을 못 줌

   • ✅ 해결법: 서브모듈 내부 코드는 상대경로로 통일

         ❌ import Button from '@/components/Button';
         ✅ import Button from '../../components/Button';
     

     
     

   3-2. env 파일 공유 문제

   • 서브모듈 내부에서는 외부 프로젝트의 .env를 참조함

   • ✅ 해결법: .env 키 이름은 최대한 중복되지 않게 명확히 구분 (RESERVATION_API_URL 등)

     
     

   3-3. 외부 라이브러리 설치 문제

   • 서브모듈이 사용하는 라이브러리는 메인 프로젝트에도 똑같이 설치되어야 함

   • ✅ 해결법: 서브모듈의 package.json을 확인해서 외부 프로젝트에 동일하게 의존성 설치

     
     

   3-4. 버전 관리 주의

   • 서브모듈은 기본적으로 고정된 커밋을 가리키기 때문에 서브모듈 레포지토리에서 업데이트가 발생하면 해당 서브모듈을 사용하고 있는 서브모듈을 수동으로 pull 받아야함

   
   
   

😎 서브모듈 사용 회고

---

• 모노레포와 비슷한 듯 다른 방식으로 독립적인 레포라 버전 관리가 쉬웠다.

• 수정사항을 이리저리 적용하지않아도 되서 코드 관리가 쉬웠다.
• 서브모듈 업데이트시 서브모듈을 사용하고 있는 레포트를 찾아가 일일히 업데이트하는 과정, 빈번한 상대경로 에러, env 관리들이 조금 귀찮았다.

• 협력자가 이해할 수 있도록 리드미 파일을 잘 쓸 필요가 있다.