HOWTO · Git

Git의 서브모듈 업데이트

이 튜토리얼은 Git에서 여러 명령을 사용하여 하위 모듈을 업데이트하는 방법을 보여줍니다.

이 페이지의 내용

Git은 상위 작업 트리의 특정 경로에 있는 저장소로 서브모듈을 관리합니다. 상위 저장소는 특정 서브모듈 커밋 하나(gitlink)를 기록하며, 브랜치 이름을 기록하거나 서브모듈의 최신 커밋을 자동으로 따라가지 않습니다. 서브모듈은 별도의 이력과 작업 트리를 가집니다. 서브모듈 안의 파일을 업데이트하는 일과 상위 저장소에 기록된 커밋을 업데이트하는 일은 서로 관련은 있지만 별개의 단계입니다.

Git 서브모듈은 커밋을 어떻게 추적하나요?

상위 저장소의 .gitmodules 파일은 서브모듈 이름과 경로를 연결하며, 보통 복제 URL도 제공합니다. 서브모듈 안에서 변경 사항을 커밋해도 그 파일들이 상위 저장소의 커밋에 포함되지는 않습니다. 대신 상위 저장소의 인덱스가 해당 경로에 새 서브모듈 커밋을 기록할 수 있습니다. 나중에 다른 사람이 상위 저장소를 복제하면 여기에 기록된 커밋이 체크아웃됩니다.

업데이트 목적은 크게 두 가지입니다. 일반 git submodule update는 상위 저장소에 이미 기록된 커밋을 체크아웃하며, 이때 서브모듈은 대개 분리된 HEAD 상태가 됩니다. --remote를 추가하면 서브모듈 원격 저장소에서 가져온 뒤 설정된 원격 추적 브랜치의 커밋을 선택합니다. 그러면 서브모듈이 상위 저장소에 현재 기록된 커밋보다 앞선 커밋으로 이동할 수 있습니다. 이 명령만으로 상위 저장소에 그 변경 사항이 커밋되지는 않습니다.

복제한 뒤 서브모듈 초기화하기

프로젝트를 복제하면서 서브모듈도 재귀적으로 가져오려면 git clone --recurse-submodules <repository-url>을 사용합니다. 이 옵션 없이 이미 복제했다면 상위 저장소에서 git submodule update --init --recursive를 실행하세요. --init은 상위 저장소의 설정을 사용해 체크아웃된 서브모듈을 초기화하고, --recursive는 중첩된 서브모듈도 초기화합니다.

git submodule init 명령은 .gitmodules에서 사용 가능한 서브모듈 설정을 로컬 .git/config로 복사합니다. 이 명령이 .gitmodules를 만들지는 않습니다. .gitmodules는 상위 프로젝트의 파일이므로 이미 존재해야 하며, 없다면 프로젝트 관리자가 추가해야 합니다. .gitmodules에서 서브모듈 URL이 바뀌었다면 가져오기나 업데이트 전에 git submodule sync --recursive를 실행해 변경된 URL을 로컬 설정에 반영하세요.

원격 저장소에서 서브모듈 업데이트하기

원격 추적 커밋을 가져와 설정된 모든 서브모듈을 업데이트하려면 상위 저장소에서 git submodule update --remote --recursive를 실행하세요. Git은 서브모듈에 설정된 브랜치를 사용하고, 설정된 브랜치가 없으면 원격 저장소의 기본 브랜치를 사용합니다. 예를 들어 .gitmodules에서 git config -f .gitmodules submodule.<name>.branch <branch>로 브랜치를 지정할 수 있습니다. 의도적으로 .gitmodules를 변경했다면 상위 저장소에서 그 변경 사항을 커밋해 협업자에게도 전달하세요.

원격 업데이트를 하면 서브모듈이 상위 저장소에 기록된 커밋과 다른 커밋에 위치할 수 있습니다. Git은 작업 트리가 깨끗한 상태라고 보장하지 않습니다. 로컬 수정 사항, 충돌, 추적되지 않는 파일이 남아 있을 수 있습니다. 계속 진행하기 전에 서브모듈과 상위 저장소의 상태를 확인하고, 커밋을 변경하기 전에 로컬 작업을 보존하거나 문제를 해결하세요.

서브모듈 하나 또는 전체 업데이트하기

옵션 뒤에 경로를 전달하면 특정 서브모듈만 업데이트할 수 있습니다. git submodule update --remote -- path/to/submodule을 실행하세요. 원격 브랜치의 최신 커밋이 아니라 상위 저장소에 기록된 커밋을 사용하려면 --remote를 생략합니다. git submodule update -- path/to/submodule은 하나를 업데이트하고, git submodule update --init --recursive는 중첩된 서브모듈까지 초기화한 뒤 기록된 커밋을 모두 체크아웃합니다. .gitmodules와 상위 작업 트리에 표시된 경로를 사용하세요. --는 옵션과 경로를 구분합니다.

설정된 원격 브랜치의 최신 커밋을 가져와 체크아웃하려면 상위 저장소에서 원격 업데이트를 사용하세요. 다른 개발자가 상위 저장소의 커밋에서 gitlink를 변경한 것처럼 프로젝트가 선택한 정확한 커밋을 사용하려면 일반 업데이트를 사용합니다.

기록할 서브모듈 커밋 검토하고 커밋하기

원격 업데이트를 하거나 특정 커밋을 체크아웃한 뒤에는 상위 저장소로 돌아와 git status와 git diff --submodule을 확인하세요. 서브모듈 경로가 변경되었다면 현재 체크아웃된 커밋이 상위 저장소 인덱스에 기록된 커밋과 다르다는 뜻입니다. 프로젝트에서 사용할 버전이 맞다면 git add path/to/submodule로 경로를 스테이징하고, git diff --cached --submodule로 검토한 뒤 상위 저장소의 변경 사항을 커밋하세요. 이 커밋은 선택한 gitlink를 기록하므로 협업자도 같은 커밋을 재현할 수 있습니다.

서브모듈 안의 파일을 변경하고 커밋했다면 해당 커밋은 서브모듈 저장소에 속합니다. 협업자도 가져와야 한다면 그 저장소에 먼저 푸시한 다음, 상위 저장소에서 변경된 서브모듈 경로를 스테이징하고 커밋하세요. gitlink를 커밋해도 서브모듈 커밋이 푸시되거나 두 저장소가 자동으로 게시되지는 않습니다. 작업 방식에 맞게 각 저장소를 따로 푸시하세요.

특정 커밋 또는 병합 전략 선택하기

알고 있는 커밋을 선택하려면 서브모듈 디렉터리로 이동해 git checkout <commit-id> 또는 git switch --detach <commit-id>로 체크아웃하세요. 커밋을 체크아웃하면 의도적으로 분리된 상태가 됩니다. 정확한 버전을 고정할 때 유용합니다. 그런 다음 상위 저장소의 상태를 확인하고, 상위 저장소에 해당 커밋을 기록하려면 서브모듈 경로를 스테이징하세요. 체크아웃만으로는 상위 저장소의 커밋이 바뀌지 않습니다.

분리된 상태로 체크아웃하는 대신 원격 변경 사항을 서브모듈 브랜치에 통합하려면 서브모듈로 이동해 git switch <branch>를 실행한 다음 git pull을 사용하세요. 이 명령은 해당 브랜치의 업스트림 설정을 따르며 병합 커밋을 만들거나 충돌 해결이 필요할 수 있습니다. 이는 상위 저장소 명령인 git submodule update --remote와 다릅니다. 후자는 설정된 원격 추적 커밋을 선택합니다. 원격 업데이트 중 병합이나 리베이스를 요청하려면 git submodule update --remote --merge 또는 git submodule update --remote --rebase를 사용할 수도 있습니다. 결과를 서브모듈에서 검토하고, 공유할 버전이라면 상위 저장소에서 그 커밋을 스테이징하세요.

흔한 업데이트 문제 해결하기

복제한 뒤 디렉터리가 비어 있거나 체크아웃된 파일이 없다면 git submodule update --init --recursive로 초기화하세요. 업데이트했는데 예상과 다른 커밋에 머물러 있다면 기록된 커밋을 사용하는 모드였는지 --remote를 사용했는지 확인하고, git config -f .gitmodules --get submodule.<name>.branch로 설정된 브랜치를 살펴보세요. 브랜치가 설정되지 않았다면 원격 저장소의 기본 브랜치가 사용됩니다.

Git이 로컬 변경 사항을 알리거나 커밋 체크아웃을 거부하면 서브모듈 자체의 git status를 확인하세요. 업데이트 전에 변경 사항을 커밋하거나 스태시하는 등 보존 방법을 마련하세요. 상위 저장소의 상태만으로는 서브모듈 내부의 모든 수정 사항을 확인할 수 없습니다. 병합이나 리베이스 중 충돌이 발생하면 해당 서브모듈 안에서 해결하고 작업을 마친 뒤 상위 저장소를 검토하세요. 마지막으로 상위 저장소에서 서브모듈 경로가 변경되었다고 해서 그 자체로 오류는 아닙니다. 체크아웃된 서브모듈 커밋이 상위 저장소에 현재 기록된 커밋과 다르다는 뜻입니다. 변경을 유지할지 결정한 뒤 의도한 변경이라면 상위 저장소에서 커밋하세요.