Git Subtree

Git Subtree

Git Subtree 는 Git 에서 제공하는 저장소 관리 도구로, 하나의 저장소 안에 다른 저장소를 포함시켜 관리할 수 있게 해주는 기능이다. 서브모듈 (Submodule) 의 대안으로 개발되었으며, 주요 저장소 (상위 저장소) 에 하위 저장소의 파일들을 직접 포함시키는 방식으로 작동한다. Git Subtree 는 복잡한 프로젝트 구조에서 코드 재사용, 공유 라이브러리 관리, 여러 저장소의 통합 관리에 유용하며, 특히 상위 저장소에서 하위 저장소의 코드를 직접 수정하고 원래 하위 저장소에 변경사항을 반영할 수 있다는 점이 큰 특징이다. 이러한 기능은 팀 협업, 라이브러리 관리, 마이크로서비스 구조의 개발 등에서 활용된다.

핵심 개념

• Git Subtree는 외부 저장소를 하나의 디렉토리처럼 포함하되, 그 내용을 상위 저장소로 직접 병합하는 방식.
• 하위 저장소는 더 이상 참조만 되는 것이 아니라 실제 코드와 히스토리가 포함됨.

목적 & 필요성

목적

Git Subtree 의 주요 목적은 다음과 같다:

• 여러 프로젝트에서 공통 코드 또는 라이브러리를 공유하고 재사용하기 위함
• 하나의 저장소에서 여러 저장소를 통합 관리가 가능하게 하기 위함
• 저장소가 분리된 파일들을 하나의 저장소에 포함시켜 개발을 진행하기 위함
• 코드 공유와 동기화를 단순화하기 위함
• 여러 개의 프로젝트를 하나로 합치기 위함

필요성

Git Subtree 는 다음과 같은 상황에서 필요성이 대두된다:

• 여러 프로젝트에 걸쳐 공통 코드나 라이브러리를 유지보수해야 할 때
• 백엔드를 마이크로서비스 구조로 개발하면서 API 응답, 데이터 모델에 같은 타입을 사용해 일관성을 유지해야 할 때
• 여러 프로젝트를 통합 관리하고자 할 때
• 핵심 디자인 파일을 여러 저장소에 포함시키고 싶을 때
• 프로젝트 히스토리를 관리하며 통합할 필요가 있을 때

주요 기능

Git Subtree 의 주요 기능은 다음과 같다:

• 하위 저장소 추가: git subtree add 명령을 통해 외부 저장소를 현재 저장소에 추가
• 하위 저장소 업데이트: git subtree pull 명령으로 외부 저장소의 변경사항을 가져옴
• 변경사항 푸시: git subtree push 명령으로 로컬에서 수정한 하위 저장소 내용을 원격 저장소에 반영
• 병합 전략: 서브트리 병합 (subtree merge) 기능을 통해 양쪽 저장소의 변경사항을 모두 반영

역할

Git Subtree 는 다음과 같은 역할을 수행한다:

• 상위 저장소에 파일을 직접 추가하고 트래킹함
• 서브트리의 원격에 있는 소스와 서브트리를 추가한 저장소의 소스가 서로 달라도 subtree merge 기능을 사용해 양쪽의 변경사항을 모두 반영할 수 있도록 함
• 상위 저장소에서 서브트리를 직접 수정하고 원격에 푸시할 수 있게 함
• 여러 저장소의 히스토리를 관리하며 재사용할 수 있도록 함

특징

Git Subtree 의 주요 특징은 다음과 같다:

• 상위 저장소에 파일을 직접 추가하고 트래킹하기 때문에 서브트리의 변경사항도 상위 저장소에 기록됨
• 서브모듈과 달리 메타데이터 파일 (예:.gitmodule) 을 생성하지 않음
• 하위 저장소 (Child) 의 내용을 상위 저장소 (Parent) 에서 일반적인 git 명령어로 관리할 수 있음
• 하위 저장소의 내용을 수정하기 위해 별도의 저장소 복사본을 유지할 필요가 없음
• 사용자가 새로운 것을 배울 필요 없이 저장소를 사용할 수 있게 함

핵심 원칙

Git Subtree 는 다음과 같은 핵심 원칙에 기반한다:

• 통합성: 여러 저장소를 하나의 저장소로 통합하여 관리
• 투명성: 사용자에게 서브트리의 존재를 숨기고 일반적인 Git 워크플로우 유지
• 양방향 동기화: 상위 저장소와 하위 저장소 간의 변경사항을 양방향으로 전파
• 히스토리 보존: 하위 저장소의 커밋 히스토리를 유지하면서 통합
• 유연성: 다양한 상황과 워크플로우에 적응할 수 있는 유연한 구조 제공

주요 원리 & 작동 원리

다이어그램

1
2
3

MainRepo/
├── project/
│   └── external-lib/ (실제 코드 포함됨)

주요 원리

Git Subtree 의 주요 원리는 다음과 같다:

• 복사 원리: Subtree 는 복사 개념으로, 하위 저장소의 코드를 상위 저장소에 복사하여 포함시킴
• 병합 원리: 서브트리 Merge 전략을 사용하여 Git 이 서브트리를 찾아 메인 프로젝트로 서브프로젝트의 내용을 병합함
• 트래킹 원리: 상위 저장소가 하위 저장소의 파일을 직접 추적하며 변경사항을 기록
• 분할 원리: git subtree split 명령으로 서브트리의 변경사항만 추출하여 별도의 커밋으로 분리 가능
• 동기화 원리: 상위 저장소와 하위 저장소 간에 push 와 pull 을 통한 양방향 동기화 가능

작동 원리

Git Subtree 는 다음과 같은 방식으로 작동한다:

1. 추가 (Add):
   • 먼저 원격 저장소를 추가한 후, subtree add 명령으로 하위 저장소를 특정 폴더에 추가함
   • 하위 저장소의 전체 커밋 히스토리가 상위 저장소로 병합됨
2. 가져오기 (Pull):
   • 원격의 하위 저장소에 변경사항이 있을 경우, subtree pull 명령으로 상위 저장소에 반영함
   • 상위 저장소에 하위 저장소의 최신 변경사항을 병합함
3. 내보내기 (Push):
   • 상위 저장소에서 하위 저장소의 내용을 수정한 후, subtree push 명령으로 원격 하위 저장소에 반영함
   • 원래 별개의 프로젝트였던 원격 저장소에 변경사항을 동기화할 수 있음
4. 분할 (Split):
   • subtree split 명령을 통해 마지막 분할 이후 변경된 내용만 찾아 별도의 커밋으로 분리함
   • 이렇게 분리된 커밋들은 하위 저장소의 원격 저장소로 푸시할 수 있음

명령어 흐름

1
2
3
4
5
6
7
8

# 1. 서브트리 추가
git subtree add --prefix=external-lib https://github.com/example/lib.git main --squash

# 2. 외부 변경 사항 병합
git subtree pull --prefix=external-lib https://github.com/example/lib.git main --squash

# 3. 외부에 변경사항 push (있을 경우)
git subtree push --prefix=external-lib https://github.com/example/lib.git main

구성 요소 및 아키텍처

Git Subtree 는 다음과 같은 구성 요소로 이루어져 있다:

1. 상위 저장소 (Parent Repository):
   • 하위 저장소를 포함하는 주 저장소
   • 모든 서브트리 조작의 기준점이 됨
   • 일반적인 git add, commit, push, pull 로 관리함
2. 하위 저장소 (Child Repository):
   • 상위 저장소에 포함될 외부 저장소
   • 원격에 독립적으로 존재하는 별도의 프로젝트
   • 상위 저장소에서는 하나의 디렉토리로 취급됨
3. 서브트리 참조 (Subtree Reference):
   • git log 에 기록되는 서브트리 관련 정보 (git-subtree-dir, git-subtree-mainline, git-subtree-split 등)
   • 서브트리의 위치와 마지막 동기화 상태를 추적하는 데 사용됨
4. 원격 참조 (Remote Reference):
   • 원격 저장소를 가리키는 참조 (remote add 로 추가됨)
   • 서브트리 명령어에서 원격 저장소 이름으로 사용됨
5. 서브트리 명령 (Subtree Commands):
   • add, pull, push, split 등의 서브트리 전용 명령어
   • 상위 저장소와 하위 저장소 간의 동기화를 관리함

Git Subtree 명령어

서브트리 추가 (add)

외부 저장소의 특정 브랜치를 현재 저장소의 하위 디렉토리로 가져온다.

1

git subtree add --prefix=   [--squash]

예시

1

git subtree add --prefix=lib https://github.com/user/library.git main --squash

• lib 폴더에 library.git 의 main 브랜치 코드를 추가하고, 커밋 내역을 하나로 합친다 (--squash 옵션).

서브트리 업데이트 (pull)

외부 저장소의 변경사항을 메인 저장소의 하위 디렉토리에 병합한다.

1

git subtree pull --prefix=   [--squash]

예시

1

git subtree pull --prefix=lib https://github.com/user/library.git main --squash

• lib 폴더의 서브트리를 최신 상태로 업데이트하며, 변경 내역을 하나의 커밋으로 합친다.

서브트리 변경사항 푸시 (push)

메인 저장소에서 하위 디렉토리 (서브트리) 에서 작업한 변경 사항을 외부 저장소로 푸시한다.

1

git subtree push --prefix=  

예시

1

git subtree push --prefix=lib https://github.com/user/library.git main

• lib 디렉토리의 변경사항을 외부 저장소의 main 브랜치에 반영한다.

서브트리 분리 (split)

하위 디렉토리의 변경 내역만 별도의 브랜치로 분리한다.

1

git subtree split --prefix= -b 

예시

1

git subtree split --prefix=lib -b lib-branch

• lib 폴더의 변경 이력만을 담은 lib-branch 브랜치를 생성한다.

원격 저장소 추가 (remote add)

외부 저장소를 원격 저장소로 등록해두면 명령어가 더 간결해진다.

1

git remote add  

예시

1

git remote add library https://github.com/user/library.git

실무에서 자주 쓰는 옵션

• --squash: 여러 커밋을 하나로 합쳐 메인 저장소의 커밋 히스토리를 깔끔하게 유지합니다.
• --prefix: 외부 저장소가 병합될 하위 디렉토리 경로를 지정합니다.

요약표

장점과 단점

분류에 따른 종류 및 유형

실무 적용 예시

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

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

최신 동향

주목해야 할 기술들

앞으로의 전망

추가 학습 주제

관련 분야 추가 학습 주제

용어 정리

참고 자료

• Atlassian 공식 가이드
• GitHub 서브트리 병합 문서
• JetBrains Space 최신 기능
• Atlassian Git Subtree 튜토리얼
• Git 공식 Git Subtree 문서
• GitHub Discussions on subtree usage
• Git Subtree 사용하기
• Git Subtree 개념 설명
• Git Subtree 사용법 - 하나의 저장소에서 여러 저장소를 관리하기
• Subtree 사용법 - ThreeSnakes의 개발 삽질 기록장
• git subtree - 프로젝트 안의 또 다른 프로젝트
• Git subtree를 활용한 코드 공유
• Git - 서브모듈
• 서브트리 Merge 개념 설명
• git subtree vs git submodule 차이점
• Git Subtree: the alternative to Git Submodule
• Managing Git Projects: Git Subtree vs. Submodule
• Git Subtree vs. Git Submodule
• Git Submodule vs Subtree
• How Apollo Manages Swift Packages in a Monorepo with Git Subtrees