Git 서브모듈(Submodule) 활용한 프로젝트 종속(외부참조) 저장소 관리

Demystifying Git Submodules: A Guide to Managing External Dependencies by Make Computer Science Great Again

하위 디렉토리에 다른 Git 저장소가 존재할 경우, 해당 디렉토리는 메인 Git 저장소에서는 서브모듈로 취급되는 경우가 많습니다. 서브모듈은 Git에서 다른 저장소를 포함하는 방법으로, 각 서브모듈은 자신만의 독립적인 저장소이며, 부모 저장소는 특정 커밋을 참조하게 됩니다.

 

서브모듈을 추가하고 관리하는 기본적인 방법은 다음과 같습니다.

1. 서브모듈 추가하기
   메인 저장소에서 하위 디렉토리에 있는 다른 저장소를 서브모듈로 추가하려면, 다음 명령어를 사용합니다.

   git submodule add <repository-url> <path-to-submodule>

   여기서 <repository-url>은 서브모듈의 저장소 URL이며, <path-to-submodule>은 메인 저장소 내에서 서브모듈이 위치할 경로입니다.
2. 서브모듈 초기화 및 업데이트
   서브모듈을 추가한 후에는 초기화하고 최신 상태로 업데이트해야 합니다.

   git submodule init
   git submodule update

3. 서브모듈 변경사항 커밋하기
   서브모듈 내에서 변경사항이 발생하면, 먼저 서브모듈에서 변경사항을 커밋하고 푸시해야 합니다. 그 후 메인 저장소에서 서브모듈의 새 커밋을 참조하도록 업데이트합니다.

   cd <path-to-submodule>
   git commit -am "Update submodule"
   git push
   cd ..
   git add <path-to-submodule>
   git commit -m "Update submodule reference"
   git push

4. 서브모듈을 포함한 복제
   다른 사람이 메인 저장소를 클론할 때 서브모듈도 함께 복제하려면, --recursive 옵션을 사용해야 합니다.

   git clone --recursive <main-repository-url>

서브모듈은 관리가 복잡할 수 있으므로, 사용 전에 충분히 이해하고 접근하는 것이 좋습니다. 서브모듈 관리와 관련된 추가적인 상황에 따라 필요한 명령어나 절차가 달라질 수 있습니다.

 

Git에서는 서브모듈이 있는 경우, 단순히 git add와 git push를 사용하는 것만으로 서브모듈의 변경사항을 자동으로 처리하지 않습니다. 여기서 중요한 부분은 서브모듈이 독립된 저장소로써 자체적인 커밋과 푸시가 필요하다는 점입니다. 서브모듈에 변경사항이 있을 경우, 그 변경사항을 메인 저장소에 반영하기 위해 다음과 같은 절차를 따라야 합니다.

1. 서브모듈에서 작업하기: 서브모듈 디렉토리로 이동하여 필요한 변경을 하고, 해당 변경사항을 커밋합니다.
2. 서브모듈을 푸시하기: 서브모듈의 변경사항을 해당 서브모듈의 원격 저장소로 푸시합니다.
3. 메인 저장소 업데이트: 메인 저장소로 돌아와서 서브모듈 디렉토리를 다시 git add 하여, 서브모듈의 최신 커밋을 메인 저장소에 반영합니다. 이는 서브모듈의 특정 커밋을 참조하는 포인터를 업데이트하는 것입니다.
4. 메인 저장소에서 커밋 및 푸시: 변경된 서브모듈 참조를 포함하여 메인 저장소에 커밋하고 푸시합니다.

만약 단순히 git add .를 수행하고 메인 저장소를 푸시하면, 서브모듈 디렉토리 내의 파일들은 추가되거나 변경된 것으로 간주되지 않습니다. Git은 서브모듈 디렉토리를 특별하게 취급하여, 그 안의 파일들을 무시하고 오직 서브모듈의 메타데이터만을 관리합니다.

 

따라서 서브모듈의 파일들이 단순히 자동으로 처리되는 것처럼 보인다면, 이는 서브모듈이 올바르게 설정되지 않았거나 Git이 해당 디렉토리를 일반 디렉토리로 인식하고 있을 가능성이 있습니다. 서브모듈의 상태를 확인하려면, 다음 명령어를 사용할 수 있습니다.

git submodule status

이 명령어는 현재 프로젝트의 서브모듈 상태와 참조하는 커밋을 보여줍니다.

 

비공개 서브모듈을 사용할 때는 접근 권한이 중요한 역할을 합니다. 비공개 서브모듈을 포함하는 프로젝트를 다룰 때, 서브모듈의 저장소에 접근할 수 있는 권한이 있어야 하며, 이를 위해 적절한 인증 방식을 설정해야 합니다. 다음은 비공개 서브모듈을 처리할 때 고려해야 할 몇 가지 주요 사항입니다.

1. SSH 키 설정: 서브모듈 저장소에 SSH를 통해 접근하는 경우, 해당 서버에 SSH 키가 올바르게 등록되어 있어야 합니다. 이는 사용자의 컴퓨터에서 서브모듈의 원격 저장소에 안전하게 접근할 수 있도록 합니다.
2. 서브모듈 URL 확인: .gitmodules 파일에서 서브모듈의 URL이 올바르게 설정되어 있는지 확인하세요. 비공개 저장소는 일반적으로 HTTPS 대신 SSH를 사용하는 URL이 필요할 수 있습니다.
   

   [submodule "PrivateSubmodule"]
       path = PrivateSubmodule
       url = git@github.com:user/PrivateSubmodule.git

3. 재귀적 클론과 풀: 메인 저장소와 서브모듈 모두를 복제하거나 업데이트할 때는 권한 문제를 피하기 위해 SSH를 사용하고 있는지 확인하고, 필요한 경우 재귀적 옵션을 사용합니다.

   git clone --recursive git@github.com:user/MainRepo.git

   또는 기존 저장소에서 서브모듈을 초기화하고 업데이트할 때는 아래와 같이 사용합니다.

   git submodule update --init --recursive

4. 에러 메시지 해결: 접근 권한 문제로 인한 에러가 발생하면, SSH 키가 서버에 등록되어 있고, 사용자 계정이 서브모듈 저장소에 접근할 수 있는 권한을 가지고 있는지 확인하세요. 인증 문제가 지속되면, 권한 설정을 재확인하거나 저장소 관리자에게 문의할 필요가 있습니다.
5. 팀원과의 권한 공유: 프로젝트를 협업하는 다른 팀원들도 비공개 서브모듈에 접근할 수 있어야 합니다. 이들 모두가 필요한 권한을 가지고 있는지 확인하십시오.

비공개 서브모듈을 사용할 때는 이와 같은 인증 및 접근 관리에 주의를 기울여야 합니다. 문제가 해결되지 않는 경우, SSH 설정, 네트워크 연결, 저장소 접근 권한 등을 체계적으로 확인해 보는 것이 좋습니다.