[Git] Git Sparse Checkout

Git Sparse Checkout: 필요한 파일만 선택적으로 가져오기

 

Git을 사용하다 보면, 전체 저장소를 클론(Clone)하는 것이 부담스러울 때가 있습니다. 특히 대형 저장소의 경우, 모든 파일을 받아야 하는 것이 비효율적일 수 있죠. 이럴 때 유용한 기능이 Git Sparse Checkout 입니다.

이 글에서는 Git Sparse Checkout이 무엇인지, 어떻게 설정하는지, 그리고 실무에서 어떻게 활용할 수 있는지를 정리해 보겠습니다.

---

1. Git Sparse Checkout이란?

Git Sparse Checkout은 저장소의 특정 디렉터리나 파일만 로컬로 가져오는 기능입니다.
즉, 전체 프로젝트를 클론 하지 않고 필요한 부분만 가져올 수 있어 디스크 공간과 네트워크 사용량을 절약할 수 있습니다.

이 기능은 대규모 모노레포(Monorepo) 프로젝트나 일부 기능만 관리하는 팀에서 특히 유용합니다.

---

2. Git Sparse Checkout 설정 방법

1) 기존 방식으로 클론 하면 모든 파일을 가져옴

보통 저장소를 클론하면 전체 파일을 받습니다.

git clone <저장소 URL>

하지만, 이렇게 하면 필요 없는 파일까지 모두 다운로드되죠.

---

2) Sparse Checkout 모드 활성화

Sparse Checkout 기능을 사용하려면 먼저 아래 명령어로 설정을 활성화해야 합니다.

git sparse-checkout init

이제 특정 폴더만 선택할 준비가 되었습니다.

---

3) 특정 디렉터리만 체크아웃하기

예를 들어, 프로젝트에서 src/moduleA와 docs/ 폴더만 필요하다고 가정해 봅시다.
아래 명령어를 사용하면 해당 폴더만 로컬로 가져올 수 있습니다.

git sparse-checkout set src/moduleA docs

이제 src/moduleA와 docs/만 남고 나머지는 사라집니다.

---

4) 원하는 폴더 추가 및 제거

추가적으로 다른 폴더를 더 가져오고 싶다면 아래 명령어를 실행하면 됩니다.

git sparse-checkout add src/moduleB

반대로, 특정 폴더를 제거하고 싶다면 다시 set 명령어를 사용합니다.

git sparse-checkout set src/moduleA

이렇게 하면 src/moduleB는 다시 제거됩니다.

---

5) 저장소 전체를 다시 가져오기

만약, Sparse Checkout을 해제하고 전체 저장소를 다시 가져오고 싶다면 아래 명령어를 실행하면 됩니다.

git sparse-checkout disable

이제 저장소의 모든 파일이 다시 로컬로 다운로드됩니다.

---

3. 실무에서 활용 사례

1) 대규모 모노레포에서 특정 모듈만 작업할 때

모노레포 방식의 프로젝트에서는 수백 개의 모듈이 한 저장소에 포함되어 있을 수 있습니다.
그중 내가 담당하는 모듈만 가져오고 싶을 때 Git Sparse Checkout이 유용합니다.

예시

git sparse-checkout set backend/user-service frontend/dashboard

이렇게 하면 백엔드의 user-service와 프론트엔드의 dashboard 폴더만 로컬에 존재합니다.

---

2) 문서나 특정 파일만 필요할 때

팀 내에서 문서(docs/ 디렉터리)만 관리하는 경우, 굳이 모든 소스코드를 받을 필요가 없습니다.

git sparse-checkout set docs

이제 docs/ 폴더만 로컬에 있고, 다른 소스코드는 필요하지 않게 됩니다.

---

3) 느린 네트워크 환경에서 최소한의 파일만 다운로드할 때

인터넷이 느린 환경에서 대형 저장소를 받을 때는 Sparse Checkout이 도움이 됩니다.
필요한 폴더만 다운로드하면 클론 속도를 빠르게 할 수 있습니다.

git clone --filter=blob:none --no-checkout <저장소 URL>
cd <저장소 이름>
git sparse-checkout init
git sparse-checkout set client/
git checkout main

이제 client/ 폴더만 받아서 사용할 수 있습니다.

---

4. 정리 및 마무리

- Git Sparse Checkout을 사용하면 대형 저장소에서도 필요한 파일만 선택적으로 가져올 수 있습니다.
- 특히 모노레포 환경, 특정 파일만 필요한 경우, 네트워크가 느린 환경에서 유용합니다.
- git sparse-checkout set <경로> 명령어를 사용하여 필요한 폴더만 로컬에 유지할 수 있습니다.

이제 Git Sparse Checkout을 활용해서 효율적으로 저장소를 관리해 보세요!