[Git] Git 2.25 이상: `git sparse-checkout set`을 이용한 특정 폴더 클론 방법

Git 2.25 이상부터는 git sparse-checkout set이라는 훨씬 간단하고 직관적인 명령어 방식이 도입되었습니다.
이 명령어를 사용하면 더 이상 .git/info/sparse-checkout 파일을 직접 수정할 필요가 없습니다.

아래에 git sparse-checkout set을 이용한 특정 폴더만 클론하는 방법을 최신 방식 기준으로 정리.

---

✅ Git 2.25 이상: git sparse-checkout set을 이용한 특정 폴더 클론 방법

---

🎯 목적

전체 Git 저장소를 클론하지 않고, 원하는 하위 폴더만 로컬로 가져오기
git sparse-checkout set 명령어를 통해 더욱 직관적이고 안전하게 설정 가능

---

🧰 사전 조건

• Git 버전 2.25 이상

  
    
  
      
      
      
      
    
  git --version
  

---

🛠 단계별 실행 방법

1. 저장소 클론 (depth 제한 없이 전체 구조는 받아야 함)

  

    
    
    
    
  
git clone --filter=blob:none --no-checkout <원격_저장소_URL>
cd <클론한_폴더>

• --filter=blob:none: 실제 파일 내용(blob)은 가져오지 않고 구조만 가져옴
• --no-checkout: 체크아웃을 생략하여 sparse 설정 전 불필요한 파일 생성을 방지

---

2. Sparse Checkout 모드 활성화

  

    
    
    
    
  
git sparse-checkout init --cone

• --cone 옵션은 단순 디렉토리 기반으로 sparse-checkout을 설정하는 최신 권장 방식입니다.

---

3. 가져오고자 하는 폴더 지정

  

    
    
    
    
  
git sparse-checkout set 폴더경로1 폴더경로2 ...

예시

  

    
    
    
    
  
git sparse-checkout set src/client docs

---

4. 원격 브랜치 체크아웃

  

    
    
    
    
  
git checkout main   # 또는 master 또는 원하는 브랜치

→ 이제 지정한 폴더만 실제로 로컬에 다운로드됩니다.

---

📂 내부 구조

  

    
    
    
    
  
<클론한_폴더>/
├── .git/
│   └── sparse-checkout/
│       └── cone-mode 활성화 관련 설정 자동 관리
├── src/
│   └── client/   # 지정한 폴더
├── docs/         # 지정한 폴더

.git/info/sparse-checkout 파일은 직접 건드리지 않아도 되고, 자동으로 관리됩니다.

---

✔️ 전체 예제 정리

  

    
    
    
    
  
git clone --filter=blob:none --no-checkout https://github.com/사용자명/저장소명.git
cd 저장소명

git sparse-checkout init --cone
git sparse-checkout set src/client docs
git checkout main

---

💬 명령어 설명

명령어	설명
--filter=blob:none	히스토리나 파일 내용은 제외하고 메타데이터만 클론
--no-checkout	clone 시 자동 체크아웃 방지
sparse-checkout init --cone	cone 모드로 sparse 체크아웃 초기화
sparse-checkout set	가져올 폴더 지정 (복수 가능)

---

🧠 참고 사항

항목	설명
cone 모드	Git 2.25부터 도입된 단순 디렉토리 기반 sparse-checkout 방식 (기존 glob 방식보다 안정적)
git sparse-checkout disable	sparse-checkout 기능 해제하고 전체 파일 다시 체크아웃
git sparse-checkout list	현재 sparse 설정된 경로 목록 확인

---

📌 마무리 요약

목적	명령어 요약
특정 폴더만 클론	git clone --filter=blob:none --no-checkout ...
sparse 기능 활성화	git sparse-checkout init --cone
폴더 지정	git sparse-checkout set 폴더1 폴더2 ...
실제 다운로드	git checkout 브랜치명

---