실무에서 유용한 Git Subtree 활용 팁 7가지

 

🎯 실무에서 유용한 Git Subtree 활용 팁 7가지

📌 1. Git Subtree 활용 브랜치 전략

• Subtree를 별도의 브랜치로 관리하면 메인 브랜치와의 충돌을 방지할 수 있습니다.
• Subtree용 별도의 임시 브랜치를 생성하여 병합 작업을 한 후 메인 브랜치에 반영하면 안정적입니다.

예시: 브랜치 활용

git checkout -b feature/update-auth-module
git subtree pull --prefix=auth-module https://gitlab.example.com/libs/auth.git main --squash
# 이후 메인 브랜치로 병합
git checkout main
git merge feature/update-auth-module

---

📌 2. 히스토리 관리가 필요한 경우 --squash 옵션 사용 권장

• Subtree 병합 시 매번 히스토리가 너무 길어지지 않도록 --squash 옵션을 적극적으로 사용하면 깔끔한 Git 이력을 유지할 수 있습니다.

git subtree pull --prefix=<폴더명> <외부 저장소> <브랜치> --squash

---

📌 3. 주기적인 업데이트 자동화

• Jenkins나 GitLab CI와 같은 CI/CD 도구를 이용해 주기적으로 외부 저장소의 변경사항을 자동으로 Subtree에 병합할 수 있습니다.

(예시: Jenkins Pipeline 예제)

stage('Update Subtree') {
  steps {
    sh '''
      git subtree pull --prefix=libs/common-utils https://gitlab.example.com/libs/utils.git main --squash
      git push origin main
    '''
  }
}

---

📌 4. Subtree 관리 스크립트 활용

• 매번 명령어를 치기 번거롭다면 관리용 Shell 스크립트를 작성해 편리성을 높일 수 있습니다.

(예시: subtree_update.sh)

#!/bin/bash
set -e

SUBTREE_PATH="libs/auth-module"
REPO_URL="https://gitlab.example.com/libs/auth.git"
BRANCH="main"

git subtree pull --prefix=$SUBTREE_PATH $REPO_URL $BRANCH --squash
echo "✅ Subtree 업데이트 완료"

chmod +x subtree_update.sh
./subtree_update.sh

---

📌 5. 충돌 발생 시 대응법

• Subtree 사용 시 간혹 충돌이 발생할 수 있습니다. 이때는 충돌이 발생한 파일을 직접 수정 후 명시적으로 커밋해줘야 합니다.

해결 절차 예시

git subtree pull --prefix=auth-module <repo> main --squash
# 충돌이 발생한 파일을 수정 후
git add <충돌파일>
git commit

• Subtree의 충돌 해결법은 일반 Git merge 충돌 해결과 동일합니다.

---

📌 6. 내부 라이브러리 배포 시 Subtree 활용

• 회사 내부에서 공통 라이브러리를 배포할 때 Subtree로 통합하면, 라이브러리 배포와 즉각적이고 간편한 통합 관리가 가능합니다.
• 내부 레포지토리에서 라이브러리를 별도로 관리하면서 각 서비스에 통합할 때 효율적입니다.

예시: 내부 모듈 병합

git subtree add --prefix=common/logging-lib https://gitlab.example.com/libs/logging.git v1.0.0 --squash

---

📌 7. Subtree 삭제 및 정리 방법

• 특정 시점 이후 Subtree가 더 이상 필요 없어진다면, 해당 디렉터리를 일반 Git 디렉터리로 취급하고 삭제하면 됩니다.

git rm -r path/to/subtree-folder
git commit -m "Remove subtree module"

• Subtree는 복사된 히스토리를 포함하기 때문에 삭제 후에도 전체 히스토리 내에는 이전 정보가 유지됩니다.

---

🚨 Subtree 사용 시 자주 발생하는 문제

• 중복 코드 이슈
  동일한 Subtree를 여러 레포지토리에서 관리하면 코드 중복이 발생할 수 있으니, 가능한 한 하나의 공통 라이브러리로 관리하거나 submodule을 병행해 관리하는 것도 방법입니다.
• 병합 주기의 불규칙성
  Subtree 병합 주기를 명확히 정하지 않으면 외부 저장소와의 코드 차이가 커져 병합 충돌이 자주 발생할 수 있습니다. 정기적으로 병합하는 것이 좋습니다.

---

🚀 추천하는 Git Subtree 사용 흐름 (Best Practice)

• Subtree용 브랜치를 분리하여 충돌 최소화
• 정기적(주간 또는 월간) 병합 주기 설정
• 스크립트나 CI/CD 파이프라인으로 자동화 관리
• 병합 시 --squash 옵션 적극 활용
• 공통 모듈이나 외부 라이브러리 병합 관리 시 적극 활용

이런 방식으로 Git Subtree를 보다 효율적이고 안정적으로 관리할 수 있습니다.