Git Submodule vs. Subtree

Git Submodule vs. Subtree

깃 (Git) 은 소프트웨어 개발에서 널리 사용되는 분산형 버전 관리 시스템으로, 복잡한 프로젝트를 효율적으로 관리할 수 있게 해준다. 대규모 프로젝트에서는 종종 여러 저장소 (repository) 에 분산된 코드를 하나의 프로젝트 내에서 통합해야 하는 필요성이 생긴다. 이러한 필요성을 해결하기 위해 깃은 두 가지 주요 접근 방식인 서브모듈 (Submodule) 과 서브트리 (Subtree) 를 제공한다.

Git Submodule 과 Git Subtree 는 모두 하나의 Git 프로젝트 안에서 다른 Git 저장소를 하위 프로젝트처럼 관리하기 위한 방식이다. 하지만 방법은 다르다.

• Submodule 은 다른 Git 저장소를 포인터로 연결하고 별도로 동기화해야 한다.
• Subtree 는 다른 Git 저장소의 특정 디렉터리 구조를 **직접 병합 (merge)**하여 포함시키는 방식으로 외부 프로젝트의 전체 히스토리를 메인 저장소에 병합한다.

이 두 접근 방식은 서로 다른 작동 원리, 사용 사례, 장단점을 가지고 있으며, 개발 팀의 워크플로우와 프로젝트 요구사항에 따라 적합한 선택이 달라질 수 있다.

flowchart TD
    subgraph Submodule
        A1[Main Repo] --> B1[.gitmodules file]
        B1 --> C1[(Submodule Pointer)]
    end

    subgraph Subtree
        A2[Main Repo] --> B2[Subtree Merged Repo with History]
    end

    style Submodule fill:#f0f8ff,stroke:#333,stroke-width:1px
    style Subtree fill:#f8fff0,stroke:#333,stroke-width:1px

기본 개념

Git Submodule은 한 Git 저장소 내에 다른 독립적인 Git 저장소를 포함할 수 있게 해주는 기능으로, 부모 저장소에서 자식 저장소의 특정 커밋을 참조하는 방식으로 작동한다. 이는 의존성 버전을 고정하여 안정성을 확보할 수 있게 한다.

Git Subtree는 외부 저장소를 현재 프로젝트의 디렉토리로 직접 병합하여 관리하는 방식으로, 상위 저장소에 하위 저장소의 파일을 직접 추가하고 트래킹한다. 이를 통해 일반적인 Git 워크플로우로 모든 코드를 관리할 수 있다.

핵심 개념 및 목적 비교

▶ 시각적 비교 다이어그램

graph LR
    A[메인 저장소] --> B[Submodule: 링크 관리]
    A --> C[Subtree: 코드 복제]
    B --> D[외부 저장소 커밋 고정]
    C --> E[외부 코드 내재화]

구성 요소 및 원리

깃 서브모듈 (Git Submodule) 은 " 참조 기반 " 접근 방식을 사용한다. 메인 저장소는 서브모듈 저장소의 특정 커밋에 대한 참조 (포인터) 만 저장하고, 실제 코드는 서브모듈 저장소에서 관리된다. 이는 " 느슨한 결합 (loose coupling)" 원칙을 따르며, 각 모듈이 독립적으로 발전할 수 있게 한다. 메인 저장소에서 서브모듈을 추가하면, 메인 저장소는 서브모듈의 특정 커밋 해시를 참조한다. 이 참조 정보는 .gitmodules 파일과 깃 인덱스에 저장된다. 서브모듈의 내용이 변경되더라도, 메인 저장소의 참조는 명시적으로 업데이트하지 않는 한 변경되지 않는다.

깃 서브트리 (Git Subtree) 는 " 통합 기반 " 접근 방식을 사용한다. 외부 저장소의 코드를 메인 저장소에 복사하여 통합함으로써, 모든 코드와 히스토리가 단일 저장소 내에서 관리된다. 이는 " 강한 결합 (tight coupling)" 원칙을 따르며, 코드 베이스의 일관성을 유지한다. 서브트리를 추가할 때, 깃은 외부 저장소의 히스토리를 메인 저장소의 히스토리에 병합한다. 이는 특별한 병합 전략을 사용하여, 외부 저장소의 커밋을 메인 저장소의 특정 서브디렉토리에 적용한다. 이 과정에서 원본 저장소의 커밋 정보를 보존하여, 나중에 변경사항을 양방향으로 동기화할 수 있다.

• Submodule 아키텍처:

1
2
3
4

Main Repo
├── .gitmodules
├── lib/
│   └── [Submodule] → 다른 Git Repo 연결 (포인터)

• Subtree 아키텍처:

1
2
3

Main Repo
├── lib/
│   └── [Subtree 병합된 Repo] → Git history 포함됨

작동 원리

깃 서브모듈 (Git Submodule) 의 작동 원리

gitGraph
    commit id: "메인 저장소 초기화"
    branch submodule
    commit id: "서브모듈 개발"
    checkout main
    commit id: "서브모듈 추가"
    merge submodule tag: "참조 커밋 업데이트"

1. 서브모듈 추가:

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

   이 명령은 지정된 저장소를 서브모듈로 추가하고, .gitmodules 파일을 생성/업데이트한다.

2. 저장소 클론 및 서브모듈 초기화:

   1 2 3

   git clone <main-repository-url> git submodule init git submodule update

   메인 저장소를 클론한 후, 서브모듈을 초기화하고 업데이트해야 서브모듈 코드를 가져온다.

3. 서브모듈 업데이트:

   1 2 3 4 5

   cd <submodule-path> git pull origin master cd .. git add <submodule-path> git commit -m "Update submodule"

   서브모듈 코드를 최신 버전으로 업데이트하려면, 서브모듈 디렉토리에서 깃 명령을 실행한 후, 메인 저장소에서 변경된 참조를 커밋해야 한다.

깃 서브트리 (Git Subtree) 의 작동 원리

gitGraph
    commit id: "메인 저장소 초기화"
    commit id: "서브트리 코드 통합"
    commit id: "서브트리 코드 수정"
    commit id: "변경사항 병합"

1. 서브트리 추가:

   1	git subtree add --prefix=<path> <repository-url> <branch> --squash

   이 명령은 지정된 저장소의 코드를 메인 저장소의 지정된 경로에 복사하고, 원본 저장소의 히스토리를 메인 저장소에 병합한다.

2. 저장소 클론:

   1	git clone <main-repository-url>

   메인 저장소를 클론하면 서브트리 코드도 함께 포함되어 있어 추가 단계가 필요 없다.

3. 서브트리 업데이트:

   1	git subtree pull --prefix=<path> <repository-url> <branch> --squash

   서브트리 코드를 최신 버전으로 업데이트하려면, 이 명령을 사용하여 원본 저장소의 변경사항을 가져와 병합한다.

4. 변경사항 업스트림 푸시:

   1	git subtree push --prefix=<path> <repository-url> <branch>

   메인 저장소에서 서브트리 코드에 변경한 내용을 원본 저장소로 푸시할 수 있다.

구조적 차이점

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# 서브모듈 구조
main-repo/
├── .git/
├── .gitmodules      # 서브모듈 참조 정보
├── project-files/
└── submodule-dir/   # 외부 저장소 참조
    └── .git         # 포인터 파일 (실제 .git은 부모의 .git/modules에 있음)

# 서브트리 구조
main-repo/
├── .git/
├── project-files/
└── subtree-dir/     # 일반 디렉토리로 취급
    └── files        # 모든 파일이 메인 저장소의 일부

장단점 비교

3. 핵심 개념 및 비교 분석

주요 기능 및 역할

목적 비교

필요성 비교

주요 기능 비교

역할 비교

특징 비교

분류에 따른 종류 및 유형

적합한 사용 사례

실무 적용 예시

실무에서 효과적으로 적용하기 위한 고려사항 및 주의할 점

최적화하기 위한 고려사항 및 주의할 점

개발자 경험 비교

성능 비교

CI/CD 통합 비교

최근근 동향

두 기술 모두 진화하고 있으며 다음과 같은 동향이 나타나고 있다:

• 하이브리드 접근법: 모노레포와 결합하여 개발은 단일 저장소에서, 배포는 개별 저장소로 하는 방식이 인기를 얻고 있다.
• 자동화 도구: CI/CD 파이프라인과의 통합과 자동화 도구를 통해 복잡한 워크플로우를 단순화하는 추세이다.
• 대안 솔루션: git-subrepo 와 같이 두 기술의 장점을 결합한 새로운 대안 도구들이 등장하고 있다.
• AI 기반 자동화: 병합 충돌 해결 및 의존성 관리를 위한 AI 기반 도구가 발전하고 있다.
• 보안 강화: 의존성 취약점 관리와 접근 제어를 강화하는 추가 기능들이 도입되고 있다.

결론적으로, Git Submodule 은 외부 의존성을 특정 버전으로 고정하고 독립적으로 관리하는 데 적합하며, Git Subtree 는 외부 코드를 프로젝트에 통합하고 단일 저장소처럼 관리하는 데 더 적합하다. 프로젝트의 특성과 팀의 워크플로우에 따라 적절한 도구를 선택하거나 하이브리드 접근법을 고려하는 것이 중요하다.

추가 학습 내용

용어 정리

참고 및 출처

• Atlassian Submodule 설명 문서
• Atlassian Subtree 설명 문서
• Git 공식 문서 - Submodule
• GitHub 블로그: Subtree 활용 사례
• Medium: Git Submodule vs Subtree (2024 업데이트)
• Git - Submodules
• Git Subtree: Alternative to Git Submodule | Atlassian Git Tutorial
• Git Submodule vs Subtree: Which Is Right for Your Project? | Graph AI
• Git submodule | Atlassian
• Introducing the Space Git Subtree | The Space Blog
• Git – Subtree | GeeksforGeeks
• Working with submodules - The GitHub Blog
• Git Submodules basic explanation | GitHub Gist
• A real world usage for git subtrees | GitHub Gist