[Git] Git 특정 폴더 클론하기 - Git 2.25 이상: git sparse-checkout set이용 (공식 최신 방식)

📋 Git 2.25 이상: git sparse-checkout set으로 특정 폴더만 클론하기 (공식 최신 방식)

✅ Git 2.25부터 도입된 sparse-checkout set 명령어는 더 이상 .git/info/sparse-checkout을 직접 수정하지 않아도 되고,
간편하고 안전하게 특정 폴더만 가져올 수 있습니다.
특히 cone 모드를 사용하면 디렉토리 단위로 매우 쉽게 관리할 수 있습니다.

🎯 목적

• 전체 리포지토리를 받지 않고
• 필요한 폴더만 안전하고 간단하게 로컬에 다운로드

🛠 초기 연결 단계 (2가지 방법 중 택1)

✅ 방법 1: git clone 사용하는 경우

파일 제외하고 구조만 가져오기

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

예시

git clone --filter=blob:none --no-checkout https://github.com/username/repository.git
cd repository

• --filter=blob:none: 실제 파일(blob)은 받지 않고 구조만 가져옴
• --no-checkout: 체크아웃을 생략하여 sparse-checkout 설정 전에 파일 생성 막음

---

✅ 방법 2: git init + remote add 사용하는 경우

mkdir repository && cd repository
git init
git remote add origin https://github.com/username/repository.git
git fetch origin

• 빈 디렉토리 초기화 후 원격 저장소 연결
• fetch로 브랜치/커밋 메타데이터만 가져옴
• 실제 파일은 가져오지 않음

---

🛠 이후 단계 (공통)

🔹 1단계: sparse-checkout 활성화

git sparse-checkout init --cone

--cone:

• 폴더 기반 디렉토리 모드 활성화
• Git 2.25 이후 기본 디렉토리 단위 sparse-checkout 모드
• glob 패턴보다 안전하고 직관적

---

🔹 2단계: 가져올 폴더 지정

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

git sparse-checkout set src/main/java docs

• 복수 폴더는 공백으로 구분해서 지정

---

🔹 3단계: 원하는 브랜치 checkout

git checkout main

• 로컬에 지정된 폴더만 selective하게 다운로드

---

📂 예시 트리 구조

repository/
├── src/
│   └── main/
│       └── java/
├── docs/

✅ 지정한 폴더만 로컬에 존재하며, 전체 리포지토리와 히스토리는 유지됨

---

🧠 왜 git checkout만 해도 파일이 받아지나요?

• git fetch로 브랜치 정보(메타데이터)만 가져왔고,
• git sparse-checkout set 으로 "어떤 폴더를 받을지" 명시해뒀기 때문에
• git checkout main 할 때 sparse-checkout 설정을 반영하여 Git이 필요한 폴더의 blob(실제 파일)만 selective 다운로드합니다.

✅ 그래서 pull 없이 checkout만 해도 필요한 폴더만 내려옵니다.

---

💡 명령어 요약

명령어	설명
git sparse-checkout init --cone	sparse-checkout 모드 활성화
git sparse-checkout set	가져올 폴더 지정
git checkout 브랜치명	파일 다운로드 (sparse 규칙 반영)
git sparse-checkout list	현재 sparse 설정된 폴더 목록 확인
git sparse-checkout disable	sparse 모드 해제, 전체 파일 복구(다시 체크아웃)

---

✅ 한 줄 요약

Git 2.25 이상에서는 sparse-checkout set을 통해 원하는 폴더만 쉽게 가져올 수 있습니다!

---

✨ 정리 흐름 시각화

1. (초기 연결)
   - clone --filter=blob:none --no-checkout
   - 또는
   - init → remote add → fetch

2. sparse-checkout init --cone

3. sparse-checkout set <폴더1> <폴더2>

4. checkout main

---

🧠 이 구조로 하면 좋은 점

항목	장점
초기 연결 유연성	clone 방식/remote 방식 모두 지원
관리 간편성	set 명령어로 폴더 목록 수정 가능
최신 Git 표준	.git/info/sparse-checkout 파일 직접 수정 불필요

---

이미 sparse-checkout 설정을 완료한 상태에서 다른 폴더를 추가하거나 바꾸고 싶을 때

✅ 현재 sparse-checkout 상태 확인

git sparse-checkout list

• 현재 설정된 폴더 목록을 확인합니다.

---

✅ 1. 폴더 추가하고 싶을 때

git sparse-checkout set --append <새폴더경로>

예시:

git sparse-checkout set --append java-workspace/example

• 기존 설정된 폴더는 유지한 채, 새 폴더만 추가됨

---

✅ 2. 폴더 바꾸고 싶을 때 (덮어쓰기)

git sparse-checkout set <새폴더1> <새폴더2>

예시:

git sparse-checkout set java-workspace/assignment

• 이전에 설정된 폴더는 사라지고, 지정한 폴더만 sparse 체크아웃됨

---

✅ 3. sparse-checkout 비활성화하고 전체 다 받고 싶을 때

git sparse-checkout disable

• sparse 설정을 해제하고, 전체 파일을 가져옵니다.

---

✅ 추가: .git/info/sparse-checkout 직접 편집도 가능

vi .git/info/sparse-checkout

• Git 2.25 이상에서는 이 파일 수동 수정은 권장되지 않지만,
  수정 후 git checkout main 등을 다시 실행하면 반영은 됩니다.

---

✅ 실무 팁

목적	명령어
폴더 추가	git sparse-checkout set --append 폴더경로
폴더 변경	git sparse-checkout set 폴더경로들
설정 확인	git sparse-checkout list
해제	git sparse-checkout disable

---