Git 서브모듈 완전 가이드 — 추가·업데이트·삭제

# 서브모듈 추가
git submodule add https://github.com/org/shared-lib.git libs/shared

# 특정 브랜치 추적
git submodule add -b main https://github.com/org/shared-lib.git libs/shared

# 추가 후 생성되는 파일
# .gitmodules — 서브모듈 설정 파일
cat .gitmodules
# [submodule "libs/shared"]
#     path = libs/shared
#     url = https://github.com/org/shared-lib.git
#     branch = main

# 커밋
git add .gitmodules libs/shared
git commit -m "feat: add shared-lib submodule"

# 방법 1: 클론 시 한 번에
git clone --recurse-submodules https://github.com/org/myproject.git

# 방법 2: 이미 클론된 경우
git submodule init
git submodule update

# 한 줄로
git submodule update --init --recursive

# 특정 서브모듈을 최신으로
cd libs/shared
git pull origin main
cd ../..
git add libs/shared
git commit -m "chore: update shared-lib to latest"

# 모든 서브모듈 한 번에 최신으로
git submodule update --remote --merge

# 병렬 업데이트 (서브모듈 많을 때)
git submodule update --remote --jobs 4

# 1. .gitmodules에서 항목 제거
git config -f .gitmodules --remove-section submodule.libs/shared

# 2. .git/config에서 제거
git config --remove-section submodule.libs/shared

# 3. 스테이징에서 제거
git rm --cached libs/shared

# 4. 파일 삭제
rm -rf libs/shared

# 5. .git/modules 정리
rm -rf .git/modules/libs/shared

# 6. 커밋
git add .gitmodules
git commit -m "chore: remove shared-lib submodule"

# 서브모듈 상태
git submodule status
# + abc1234 libs/shared (v1.2.3)
# ^ = 앞서 있음, - = 초기화 안 됨, + = 변경됨

# 서브모듈 포함 전체 상태
git status --recurse-submodules

# 서브모듈 요약
git submodule summary

# 문제: 서브모듈이 빈 디렉터리
git submodule update --init --recursive

# 문제: detached HEAD 상태
cd libs/shared
git checkout main
git pull

# 문제: URL 변경 후 업데이트 안 됨
git submodule sync
git submodule update --init

# 문제: 서브모듈 변경사항을 부모 레포가 인식 못 함
cd ..
git add libs/shared    # 포인터(커밋 해시)를 업데이트
git commit -m "chore: update submodule pointer"

- uses: actions/checkout@v4
  with:
    submodules: recursive      # 서브모듈 포함 체크아웃
    token: ${{ secrets.PAT }}  # private 서브모듈은 PAT 필요