</>Logs of Lety Atelier
← 블로그 목록으로
•⏳ 3 MIN READ

프로젝트 내부에 submodule 만들기

git submodule, 서브모듈을 다른 프로젝트에서도 사용할수 있도록 원 프로젝트에서 분리하는 방법을 설명합니다

#Git#submodule#monorepo

문제 상황 및 해결 로그

프로젝트 폴더 안에 새로 패키지 폴더를 만들고 git에 추가했습니다. 내부에 있는 이 패키지 폴더에서 브랜치를 내고 수정하고 싶을때 어떻게 하나요?

1. 모노레포 방식 (기본 방식)

대부분의 경우 이렇게 하면 됩니다. 새 패키지 폴더에서 다시 git init 을 하고 않고 사용하는 방식입니다.

정신건강에도 좋고, 간단합니다.

2. Git submodule 방식

강력한 분리가 필요한 경우.

  1. 오픈소스 라이브러리 처럼 별도의 git 이 필요한 경우
  2. 다른 앱에도 공유할 공용 라이브러리
  3. 독립적인 버전 관리가 필요한 경우

여기서는 2번방식 : git submodule 로 분리하는 방법을 설명합니다.

1단계: 패키지 폴더를 독립된 저장소로 분리하기 (Untangle)

먼저 메인 프로젝트의 멱살(?)을 잡고 있는 패키지 폴더를 풀어주어야 합니다.

  1. 원격 저장소 생성: GitHub(또는 GitLab 등)에 패키지만을 위한 새로운 빈 레포지토리(예: neon-pitch-core)를 하나 생성합니다.

  2. 메인 프로젝트에서 추적 해제: 메인 프로젝트의 루트 경로에서 터미널을 열고, 기존에 추가했던 패키지 폴더의 Git 추적을 해제합니다. (파일은 지워지지 않고 Git의 시야에서만 사라집니다.)

    Bash

    git rm -r --cached 패키지_폴더명

  3. 패키지를 독립된 Git으로 초기화:

    Bash

    cd 패키지_폴더명
git init
git add .
git commit -m "Initial commit for shared package"
git branch -M main
git remote add origin [새로_만든_패키지_레포지토리_주소]
git push -u origin main

이 때, 패키지명은 개별 패키지 폴더 이름을 말합니다. 예를 들어 ./packages/ 라는 폴더 안에 package A, B, C 이런 식으로 여러 패키지가 있다면 그 각각의 패키지에 대해서 수행해야합니다.

2단계: 메인 프로젝트에 서브모듈로 다시 연결하기

이제 독립된 패키지를 메인 프로젝트의 서브모듈로 예쁘게 장착합니다.

  1. 메인 프로젝트의 루트 경로로 다시 이동합니다. cd ..

  2. 서브모듈로 패키지를 추가합니다. 여기서 레포지토리 주소는 (https://github.com/유저명/패키지명.git) 와 같은 주소를 말합니다.

    Bash

    git submodule add [새로_만든_패키지_레포지토리_주소] 패키지_폴더명

  3. 메인 프로젝트에 .gitmodules 파일이 생성된 것을 확인하고 커밋합니다.

    Bash

    git commit -m "chore: add shared package as submodule"

3단계: 실전 작업! 패키지 내부에서 브랜치 따고 수정하기

이제 셋업이 끝났으니, 유저님이 원하시던 “패키지 내부에서 브랜치를 내고 수정하는” 일상적인 작업 흐름입니다.

1. 패키지 폴더로 진입하여 브랜치 생성 에디터(VS Code 등)에서 터미널을 열고 패키지 폴더로 들어갑니다. 여기가 독립된 세계입니다.

Bash

cd 패키지_폴더명
git checkout -b feature/update-core-logic

2. 코드 수정 및 커밋, 푸시 패키지 코드를 마음껏 수정하고 패키지 저장소에 푸시합니다.

Bash

git add .
git commit -m "feat: 속도 파라미터 로직 추가"
git push origin feature/update-core-logic

(필요하다면 패키지 레포지토리에서 main으로 PR을 날리고 Merge 합니다.)

3. ⭐️ 중요: 메인 프로젝트에 ‘최신 버전’ 알려주기 패키지가 업데이트되었으니, 메인 앱에게 “라이브러리 버전이 올랐어!“라고 알려주어야 합니다. 다시 메인 프로젝트 루트로 나옵니다.

Bash

cd ..

터미널에서 git status를 쳐보면 패키지 폴더명 옆에 (new commits)라고 뜰 것입니다. 이를 메인 프로젝트에 커밋합니다.

Bash

git add 패키지_폴더명
git commit -m "chore: update shared package pointer to latest commit"

패키지 매니저 연동 팁 (Flutter/Dart 기준)

이 라이브러리를 플러터나 다트 환경에서 사용할 경우, 메인 프로젝트의 pubspec.yaml에 이 서브모듈 폴더를 로컬 경로로 잡아주면 개발할 때 아주 쾌적합니다.

YAML

dependencies:
  my_shared_package:
    path: ./패키지_폴더명 # 서브모듈로 땡겨온 폴더 경로

이렇게 해두면:

  1. 라이브러리(패키지 폴더) 코드를 수정하자마자 메인 앱에 즉각 반영되어 테스트가 가능하고,
  2. 버전 관리는 Git 서브모듈을 통해 완벽하게 독립적으로 이루어집니다.