Git sparse-checkout + partial clone으로 모노레포 온보딩 속도 최적화 가이드

모노레포 온보딩이 느린 진짜 이유

 

대형 모노레포는 첫 클론과 초기 빌드에서 과도한 시간과 저장 공간을 요구합니다. 팀에 합류하자마자 수십 GB의 이력과 불필요한 디렉터리를 내려받는 일이 흔합니다.

 

결국 필요한 건 일부 디렉터리와 최신 스냅샷인데, 전체 히스토리까지 받느라 대기 시간이 길어집니다. 이 글은 Git의 sparse-checkout과 partial clone을 함께 써서 초반 내려받기와 체크아웃 범위를 최소화하는 방법을 다룹니다.

 

검색 의도는 “모노레포에서 필요한 부분만 빠르게 받는 법”에 가깝습니다. 여기서는 한 번에 모든 개념을 다루지 않고, 온보딩 속도에 직접 영향주는 핵심 옵션과 안전한 적용 순서를 먼저 설명합니다.

 

> 트레이드오프: 서버와 네트워크 상태에 따라 일부 이력 조회가 지연될 수 있습니다. 온보딩 구간에서는 속도 이득이 크지만, 과거 커밋 탐색이 잦다면 전략을 혼합하는 편이 좋습니다.

 

필요한 것만 받는 두 가지 키: partial clone과 sparse-checkout

 

모노레포 온보딩에서 핵심은 “최신 스냅샷만, 필요한 디렉터리만”입니다. partial clone은 히스토리(오브젝트)를 필요할 때 가져오고, sparse-checkout은 워킹 디렉터리에 펼칠 경로를 제한합니다.

 

예를 들어 프론트엔드 팀이 apps/web과 packages/ui만 쓰는 상황을 가정해 보겠습니다. partial clone으로 거대한 과거 커밋 다운로드를 미루고, sparse-checkout으로 두 폴더만 체크아웃하면 초기 대기 시간과 디스크 사용량이 눈에 띄게 줄어듭니다.

 

동작 흐름은 간단합니다. 원격에서 얕은 메타데이터만 받음 -> 필요한 파일을 체크아웃 목록에 등록 -> 실제로 열람하거나 빌드할 때 해당 오브젝트만 추가 다운로드합니다.

 

이 방식은 네트워크 전송량을 줄이는 데 직접적으로 작동합니다.

 

> 안티패턴: 처음부터 리포 전체 패턴을 넓게 지정하면 sparse-checkout 이점이 사라집니다. 팀별 상위 폴더 1~2개로 시작하고, 필요 시 경로를 점진적으로 추가하는 편이 안전합니다.

 

깃 최소 다운로드로 빠른 온보딩

 

최신 스냅샷만, 필요한 폴더만 받는 방법입니다. 새 빈 폴더에서 실행하면 로컬 충돌을 줄일 수 있습니다.

 

- git 2.30+ 권장, 리모트가 partial clone 지원 여부 확인
- 미리 열 폴더 정하기: 예) apps/web, packages/ui
- 느린 네트워크면 가장 작은 범위부터 시작

 

partial clone은 과거 기록(이력) 받기를 미룹니다. 이어서 sparse-checkout으로 작업 폴더에 펼칠 경로를 제한합니다.

 

# 1) partial clone: 파일 내용은 나중에 받기
git clone --filter=blob:none --no-checkout <REMOTE_URL> repo
cd repo

# 2) sparse-checkout: 필요한 경로만 열기
git sparse-checkout init --cone
git sparse-checkout set apps/web packages/ui

# 3) 최신 스냅샷만 체크아웃
git checkout main

 

--filter=blob:none은 파일 내용을 지연 가져옵니다. sparse-checkout set에 지정한 경로만 워킹 디렉터리에 생깁니다.

 

작업 범위를 넓힐 때만 경로를 더하세요. 그때 필요한 파일만 추가로 내려받습니다.

 

# 4) 폴더 추가
git sparse-checkout add tools/scripts

# 5) 과거 이력 잠깐 필요할 때(선택)
git fetch --deepen=200

 

add는 파일 열기·빌드 시 네트워크 왕복이 생길 수 있습니다. deepen은 필요한 만큼만 이력을 얕게 늘립니다.

 

> 체크포인트
> - CI 스크립트·루트 훅 사용 시 누락 폴더로 실패할 수 있습니다. 공통 폴더(config, .tools 등)를 함께 포함하세요.
> - 대용량 파일은 LFS와 충돌할 수 있어 팀 규칙을 확인하세요.
> - 과거 커밋 탐색이 잦다면 그때만 deepen 폭을 키우는 편이 효율적입니다.

 

흔한 실수와 안전한 선택 기준

 

partial clone과 sparse-checkout을 섞을 때 가장 흔한 실수는 범위를 너무 넓게 여는 것입니다. 처음엔 최소 경로만 열고, 빌드나 테스트에 필요할 때만 한 폴더씩 추가하는 편이 안전합니다.

 

다음 체크리스트를 기준으로 시작 범위를 정하세요.

 

- 팀 역할 기준 경로만 선택: apps/web, packages/ui 처럼 구체적으로
- 빌드 입력 경로 포함: 공용 config, tsconfig/base, env 템플릿 확인
- CI 스크립트가 참조하는 스크립트/툴체인 경로 포함

 

> 안티패턴: init 단계에서 repo 루트나 packages/* 같은 와일드카드를 한꺼번에 열면 사실상 전체 체크아웃과 다르지 않습니다. 온보딩 이점이 사라집니다.

 

partial clone 뒤에는 과거 이력 탐색이 느릴 수 있습니다. 잦은 git blame/grep 과거 조회가 필요하면 다음 기준을 참고하세요.

 

- 과거 추적이 드문 온보딩·버그 재현 위주: partial clone 유지
- 과거 이력 검토가 많은 리팩터링 단계: 특정 서브트리만 depth 확대 또는 필요 시 fetch --filter 해제
- 장기 브랜치 운용: 레퍼런스만 얕게 유지하고, 자주 쓰는 폴더 이력만 선택적으로 받아오기

 

리모트 지원 여부도 놓치기 쉽습니다. 서버가 partial clone을 지원하지 않으면 --filter가 무시되거나 성능 이득이 거의 없습니다.

 

가능한 선택지는 다음과 같습니다.

 

- 지원 O: --filter=blob:none로 시작, 필요 시 경로 추가
- 지원 X: 얕은 클론(depth) + sparse-checkout으로 절충
- 프록시/미러 사용: 사내 미러 서버에서 필터링 가능 여부 확인

 

지금 바로 적용할 온보딩 최소 세트

 

partial clone은 과거 오브젝트 전송을 미루고, sparse-checkout은 워킹 디렉터리를 좁힙니다. 온보딩에서는 “최신 스냅샷 + 필요한 폴더만”으로 시작하는 것이 가장 빠릅니다.

 

바로 실행하려면 아래 순서로 진행하세요.

 

- 새 디렉터리에서 git clone --filter=blob:none --no-checkout
- git sparse-checkout init --cone
- git sparse-checkout set <팀에 필요한 경로만>
- 빌드/테스트에 필요한 공용 설정 경로를 추가로 set

 

필요할 때만 범위를 넓히면 네트워크 비용을 아낄 수 있습니다. 과거 커밋 탐색이 잦다면 특정 시점에만 전체 fetch로 전환하는 하이브리드 운영이 유용합니다.

 

> 팁: set 목록은 팀별 프리셋으로 문서화해 두면 새 구성원이 같은 패턴으로 빠르게 시작할 수 있습니다.