[Git] git submodule 서브모듈 활용하기: 다운받기(clone), 변경하기(update), 추가하기(add), 삭제하기(deinit) + 특정 폴더를 submodule로 추출하는 방법

💡 본 문서는 '[Git] git submodule 서브모듈 활용하기'에 대해 정리해놓은 글입니다.
git을 사용하다보면 특정 폴더를 공통모듈로 관리하고 싶다는 생각이 듭니다. 이럴 때 사용할 수 있는 것이 git submodule이며, 'submodule이 적용되어 있는 레포지토리 클론하는 방법', 'submodule 추가/제거하는 방법', '특정 폴더를 submodule로 추출하는 방법'에 대해 자세히 정리하였으니 참고하시기 바랍니다.

1. submodule 을 포함한 git에서 작업하기

1) submodule 을 포함하는 git 저장소를 clone 하기

submodule 을 사용하는 저장소를 clone 하는 경우, init 과 함께 update 를 수행이 필요하다.

$ git clone --recursive https://github.com/username/repo.git

위 명령어를 사용하면 해당 저장소가 참조중인 submodule 들을 같이 clone 하여 적절한 경로에 위치시켜 줄 것이다 (submodule 을 포함하는 submodule 역시 함께 처리된다).

$ git clone https://github.com/username/repo.git
$ git submodule update --init --recursive

이러한 방법은 통상적인 방법으로 clone 을 수행한 직후 git submodule update --init --recursive 명령어를 실행하는 것과 동일한 효과를 갖는다.

2) submodule 을 최신 버전으로 update한후, master를 push

submodule 작업시 부모 프로젝트 내부에서 작업하더라도 submodule 자체를 업데이트 해줘야 작업 내용이 반영됩니다.

$ cd <submodule path>
$ git pull
$ git status
$ git add band
$ git commit -m "updated band"
$ git push

부모 repo에서 자식 프로젝트 작업시 주의할 점!!

자식 프로젝트 작업후, 리모트에 커밋하지 않고 git submodule update하면, 부모 repo가 참조하는 커밋으로 체크아웃되어, 작업 내용이 삭제됩니다!!

커밋만 하고 푸시하지 않은 상태라면, 로컬 커밋에서 찾을 수도 있으나, 별도 브랜치가 없으면 찾기 어렵게 됩니다. 따라서, 부모 repo에서 자식 프로젝트 작업시, 반드시 별도 브랜치를 따서 작업할 것을 추천합니다.

3) submodule 상태 확인

submoudle status명령은 현재 sub 모듈이 가리키는 커밋 상태를 확인합니다.

$ git submodule status

2. submodule 추가, 업데이트 및 제거하기

1) submodule 추가하기

다른 저장소에 있는 paper이라는 프로젝트를 작업중인 저장소의 서브모듈로 추가하려고 할 경우, 아래와 같이 git submodule add <repository> [path]을 사용하여 submodule을 add하면 됩니다.

$ git submodule add https://github.com//paper paper

git status를 확인해보면 .gitmodule과 paper폴더가 추가된 것을 확인할 수 있고, .gitmodule 에는 git에서 관리되는 서브모듈에 정보가 들어있고, 아래 내용이 추가됩니다.

[submodule "paper"]
    path = paper
    url = https://github.com//paper.git
    branch = master

.git/config 에도 아래 내용이 추가됩니다.

[submodule "paper"]
    url = https://github.com//paper.git

이 때 shot에는 paper라 폴더가 생성되지만, 그 안에는 아무것도 없기 때문에, submodule update를 사용하여 paper의 내용을 명시적으로 다운로드합니다 (새버전 git에서는 자동 다운로드합니다)

$ git submodule update --init --recursive

모든 것이 잘 되었다면, 변경점을 커밋하고 paper폴더를 shot저장소에 추가합니다.

gitHub에 paper폴더 아이콘에 작은 표시를 붙여 이것이 서브모듈임을 나타냅니다.

2) submodule 업데이트하기

다음의 명령을 통해 내부에 포함되어 있는 submodule을 최신 커밋으로 업데이트할 수 있습니다.

$ git submodule foreach git pull --rebase

3) submodule 제거하기

삭제는 deinit 명령으로 해당 모듈을 초기화하고, rm 명령으로 해당 폴더를 삭제후, git rm 명령으로 git에서도 해당 폴더를 제거합니다.

$ git submodule deinit -f band
$ rm -rf .git/modules/band
$ git rm -f band

3. 하위 폴더를 새 리포지토리로 분할 (git submodule 활용)

magician 이라는 신규 프로젝트를 시작하기로 했는데, 여기서 band가 유용하다고 가정합니다. shot을 위해 만든 band를 독립적인 저장소로 분리한 후, 두 개의 프로젝트에 서브로 추가해 보겠습니다.

band를 shot에서 추출하려면, git filter-branch 명령으로 band 관련된 커밋만 남길 수 있습니다. 이는 저장소 이력을 재작성하여 band가 원래 저장소에 포함되지 않은 것처럼 보이게 합니다.

1) A 이름의 local 저장소 생성

shot 안의 band를 자체 저장소로 동작하게 하기 위해 shot 복사본을 band이름으로 생성합니다.

cd ..
cp -r shot band

2) A 관련 폴더 및 히스토리만 추출

이제 band 폴더의 파일과 커밋 히스토리만 남깁니다.
사용 방법은 git filter-branch --subdirectory-filter <folder name> <branch name> 입니다.

cd band
git filter-branch --subdirectory-filter band -- --all

3) A 이름의 remote 저장소 생성 및 update

github에서 band라는 새로운 저장소를 만들고 remote를 band로 update합니다.

git remote -v
git remote set-url origin https://github.com//band
git push -u origin master

4) 원본 저장소에서 A 폴더 삭제

shot저장소에서 band폴더를 삭제합니다

git rm -r band
git commit -m "Remove band (preparing for submodule)"

5) A를 부모 저장소에 submodule로 추가

shot에 band를 서브모듈로 만듭니다

git submodule add https://github.com//band band
git commit -m "band submodule"

이제, 부모 저장소인 shot', 두개의 서브 저장소인 paper과 band`를 포함한 세개의 저장소가 됩니다. shot 히스토리를 보면, band가 폴더일 때 만들었던 커밋들이 남아있습니다. 즉, 폴더를 삭제하더라도 히스토리가 삭제되지 않습니다.

참고

• [Blog] git 서브모듈: 추가하기, 변경하기,삭제하기: https://yztech.tistory.com/95
• [Blog] 9.1: submodule 을 포함하는 git 저장소를 clone 하기: https://nochoco-lee.tistory.com/87
• [Official Docs] Github 하위 폴더를 새 리포지토리로 분할: https://docs.github.com/ko/get-started/using-git/splitting-a-subfolder-out-into-a-new-repository
• [Blog] 9.2: submodule 갱신 (update) 하기: https://nochoco-lee.tistory.com/88