Github Repository를 서브모듈로 연결하기

 

깃허브를 사용하다보면 특정 리포지토리에 다른 리포지토리를 연결하여 사용이 필요할 때가 있다. 예를 들면 프로젝트 내부에 다른 프로젝트를 포함하여 독립적인 커밋을 관리하거나, 단순히 마크다운 문서파일이나 이미지 파일만 따로 보관하고 업데이트 하는 저장소를 메인 깃 저장소에 연동하고 싶거나 할 때이다.

 

또한, 깃허브 블로그를 운영한다면 다른 사람이 만든 테마 저장소의 theme 디렉토리만 연결 할 때에도 해당 리포지토리를 따로 연결해서 사용하면 모듈화가 가능하므로 불필요한 기능이나 파일, 전체적인 업데이트로부터 자유로울 수 있어 관리도 편하고 백업도 편하다. 이렇게 다른 깃 저장소를 현재 저장소 안에 포함시키는 기능을 Github에서는 하위 모듈(서브모듈, Submodule) 설정으로 제공하고 있다.

 

깃허브를 효과적으로 활용하기 위해 여러 리포지토리를 연결하는 상황에서, 서브모듈을 사용하면 프로젝트 관리와 코드 재사용이 편리해진다. 서브모듈을 통해 다른 저장소의 특정 버전을 현재 프로젝트에 통합하는 방법을 아래와 같이 공유해본다.

---

서브모듈이란? (Git Submodule)

서브모듈은 다른 깃 저장소를 현재 저장소 안에 포함시키는 기능으로, 하나의 프로젝트 안에서 다른 프로젝트를 사용하는 것과 비슷합니다. 서브모듈을 통해 외부 저장소의 특정 버전을 현재 프로젝트에 포함시킬 수 있다.

 

예시: 외부 라이브러리를 서브모듈로 추가하기

 

1. 새로운 저장소 생성

먼저 새로운 저장소를 만든다. 예를 들면 이 저장소는 특정 외부 라이브러리가 포함되어 있는 저장소이다.

2. 서브모듈로 추가

현재 프로젝트의 루트 디렉토리에서 다음 명령어를 실행하여 서브모듈을 추가한다.

경로 형식은 아래와 같고 git bash 등의 터미널 등을 이용할 수 있다.

git submodule add <연동할 깃 저장소 주소.git> <연동할 메인 저장소의 경로>

 

예를 들어 나의 현재 프로젝트가 /mainproject 이고, /mainproject/external 경로에 특정 외부 라이브러리 리포지토리를 연동하고 싶다면 아래와 같은 명령어를 사용할 수 있다.

# 현재 내 위치: /mainproject

git submodule add https://github.com/example/external-library.git external

 

또 다른 예시로, 이미지만 저장하는 img.git 저장소를 내 프로젝트의 /mainproject/static/img 디렉토리에 서브모듈로 연동한다고 하면 아래와 같이 하위 경로를 추가할 수 있다.

# 현재 내 위치: /mainproject

git submodule add https://github.com/example/img.git static/img

 

3. 서브모듈 업데이트

서브모듈이 추가되면 다음 명령어로 서브모듈을 업데이트한다. 아래 명령어는 서브모듈을 초기화하고 업데이트한다.

git submodule update --init --recursive

 

 

4. 서브모듈 사용

이제 외부 라이브러리를 사용할 수 있으며, 코드에서 external 폴더를 참조하여 외부 라이브러리의 기능을 활용할 수 있다.

 

 

서브모듈 제거하기

서브모듈을 연동했지만 잘못된 경로에 연동했거나 잘못된 리포지토리 주소를 넣었을 수 있다.

연동을 제거하려면 아래와 같은 단계를 따를 수 있다.

1. .gitmodules 파일에서 서브모듈 관련 정보를 삭제
   * .gitmodules 파일은 서브모듈을 연동하면 루트 디렉토리에 자동으로 생성된다.
   
2. .git/config 파일에서 서브모듈 섹션을 찾아 제거
3. git rm --cached <submodule_path> 명령어를 사용하여 서브모듈을 스테이징 영역에서 제거
   * submodule_path는 기존에 서브모듈을 연결해 놨던 디렉토리 (예: static/img)를 말한다.
   
4. 서브모듈의 실제 디렉토리를 제거
5. 변경 내용을 커밋하고 원격 저장소에 푸시

만일 기존에 서브모듈을 연결해놨던 디렉토리가 _posts 이고, 스테이징 된 파일을 확인하려면 아래의 명령어를 쓸수 있다.

git ls-files --stage _posts