Git sparse-checkout 사용법

본문 중간의 쿠팡 추천 상품 구매시 쿠팡 파트너스에서 일정액의 수수료를 제공받습니다.

Git sparse-checkout 사용법

git sparse-checkout은 작업 트리에 필요한 경로만 체크아웃해서 큰 저장소를 더 가볍게 다루게 해 주는 Git 기능이다. Git 공식 문서 기준으로 이 기능은 monorepo처럼 디렉터리가 많은 저장소에서 특정 하위 경로만 집중해서 작업할 때 유용하다.

핵심은 세 가지다. 어떤 경로를 작업 트리에 펼칠지, 패턴을 cone mode로 단순하게 관리할지, 그리고 이것이 전체 저장소를 부분 clone하는 기능과는 어떻게 다른지다. 이 글은 Git 공식 문서를 기준으로 init, set, add, reapply, disable와 git clone --sparse의 관계를 정리한다.

Git sparse-checkout은 정확히 무엇을 줄여 줄까?

공식 문서에서 sparse checkout은 working tree에 있는 파일 수를 줄이는 기능으로 설명된다. 저장소 이력 자체를 없애는 것이 아니라, 현재 작업 디렉터리에 펼쳐지는 경로 범위를 제한하는 방식에 가깝다.

그래서 저장소 전체 브랜치 구조를 이해하거나 커밋 기록을 조회하는 일과, 실제 작업 트리에 어떤 파일을 꺼내 둘지를 분리해서 생각해야 한다. 디스크 사용량과 파일 탐색 복잡도를 줄이고 싶을 때 특히 직접적인 효과가 있다.

언제 sparse-checkout이 가장 잘 맞을까?

가장 대표적인 경우는 monorepo에서 한두 개 서비스 디렉터리만 수정할 때다. 예를 들어 frontend/만 담당하는 개발자가 매번 백엔드, 인프라, 문서 디렉터리까지 모두 작업 트리에 펼칠 이유는 크지 않다.

반대로 저장소 전체를 자주 grep 하거나, 여러 하위 디렉터리를 동시에 리팩터링하거나, 빌드 시스템이 광범위한 경로를 기본 전제로 삼는다면 sparse-checkout이 기대만큼 단순하지 않을 수 있다. 이 경우에는 패턴 관리 비용까지 같이 봐야 한다.

가장 먼저 알아둘 명령은 무엇일까?

목적	예시 명령	의미
초기화	git sparse-checkout init --cone	cone mode 기준으로 sparse checkout 사용을 시작한다.
대상 경로 지정	git sparse-checkout set frontend docs	작업 트리에 남길 디렉터리를 지정한다.
대상 경로 추가	git sparse-checkout add scripts	기존 설정을 유지한 채 경로를 더 포함한다.
패턴 재적용	git sparse-checkout reapply	충돌이나 설정 변경 뒤 sparse 규칙을 다시 작업 트리에 반영한다.
해제	git sparse-checkout disable	전체 작업 트리로 되돌린다.

실무에서는 set과 add의 차이를 분명히 기억하는 편이 중요하다. set은 현재 sparse 목록을 새로 정하는 성격이 강하고, add는 이미 있는 범위에 경로를 더하는 명령이다.

cone mode는 왜 기본값처럼 다뤄질까?

Git 공식 문서는 cone mode를 디렉터리 단위로 다루는 단순한 패턴 집합으로 설명한다. 지정한 디렉터리와 그 조상, 그리고 형제 디렉터리의 즉시 하위 파일까지 포함하는 방식이라 사람이 읽고 유지하기 쉽다.

대부분의 개발 저장소는 파일 개별 패턴보다 디렉터리 기준으로 작업 범위를 정하는 경우가 많다. 그래서 특별한 glob 패턴이 꼭 필요하지 않다면 cone mode가 운영 부담이 더 적다.

non-cone mode는 언제만 고려하면 될까?

공식 문서에 따르면 non-cone mode는 보다 일반적인 패턴을 다룰 수 있지만, 복잡성과 성능 측면에서 tradeoff가 있다. 파일 단위나 복잡한 include-exclude 패턴이 필요할 때만 신중하게 선택하는 편이 맞다.

즉 "특정 디렉터리만 작업하겠다"는 수준이라면 cone mode로 충분한 경우가 많다. non-cone mode가 필요한 이유를 명확히 설명하기 어렵다면 기본 선택지로 보기에는 과하다.

 

 

git clone --sparse와 무엇이 다를까?

git clone --sparse는 clone 시점부터 최상위 디렉터리만 initially present 하도록 시작하는 옵션이다. 이후 필요한 경로는 git sparse-checkout set이나 add로 넓혀 갈 수 있다.

반면 기존에 이미 clone한 저장소에서도 git sparse-checkout은 바로 적용할 수 있다. 즉 새로 받는 저장소라면 clone --sparse, 이미 로컬에 있는 저장소라면 sparse-checkout 명령군으로 이해하면 흐름이 단순하다.

partial clone과 sparse-checkout은 같은 기능일까?

같지 않다. Git 공식 문서에서 git clone --filter=<filter-spec>는 object 전송 범위를 줄이는 partial clone 계열 옵션이고, sparse-checkout은 작업 트리에 펼쳐지는 파일 범위를 줄이는 기능이다.

그래서 네트워크 전송량과 로컬 object 저장까지 줄이고 싶다면 partial clone을 같이 검토할 수 있고, 일단 저장소는 받아 두되 작업 디렉터리만 가볍게 유지하고 싶다면 sparse-checkout만으로도 목적을 달성할 수 있다. 둘은 겹치지만 층위가 다르다.

reapply는 언제 필요한가?

Git 공식 문서는 merge, rebase, conflict 처리, 또는 다른 명령으로 인해 sparse specification과 working tree 상태가 어긋난 경우 reapply를 사용할 수 있다고 설명한다. 설정은 남아 있는데 실제 파일 배치가 기대와 달라졌다면 이 명령이 복구 역할을 한다.

특히 도구가 자동으로 파일을 만들거나 충돌 처리 과정에서 원래 sparse 범위 밖 파일이 나타난 뒤 정리 기준이 애매해졌다면, 먼저 현재 패턴을 확인하고 reapply로 규칙을 다시 반영하는 편이 안전하다.

sparse index는 꼭 같이 켜야 할까?

공식 문서 기준으로 sparse index는 sparse-checkout 사용자에게 더 적은 index 크기와 일부 명령 성능 개선을 제공할 수 있는 기능이다. 다만 모든 외부 도구나 오래된 워크플로가 이를 자연스럽게 다루는지는 별도 확인이 필요하다.

즉 저장소가 매우 크고 Git 자체 명령 성능이 병목이라면 가치가 있지만, 팀 도구 호환성을 먼저 봐야 한다. 현재 운영 환경이 표준 Git CLI 중심인지, IDE나 스크립트가 index 내부 가정에 민감한지에 따라 판단이 달라질 수 있다.

FAQ

Q. 지정하지 않은 경로의 파일은 완전히 삭제되나?

작업 트리에서는 sparse specification 밖 경로가 보이지 않거나 제거될 수 있지만, 저장소 이력 자체가 사라지는 것은 아니다. 핵심은 working tree 노출 범위를 줄이는 것이라는 점이다.

Q. 디렉터리 하나만 작업하는 팀에 기본값으로 권할 만한가?

그럴 수 있다. 특히 monorepo에서 디렉터리 경계가 분명하고, 팀이 주로 한 하위 트리만 수정한다면 cone mode 기반 sparse-checkout은 운영상 이해하기 쉬운 선택지다.

Q. 전체 파일이 다시 필요해지면 어떻게 되돌리나?

공식 문서 기준으로 git sparse-checkout disable을 쓰면 sparse checkout을 끄고 전체 작업 트리로 돌아갈 수 있다. 잠깐 경량 모드로 쓰다가 일반 clone처럼 복원할 수 있다는 점이 장점이다.

정리

git sparse-checkout은 큰 저장소에서 필요한 경로만 작업 트리에 펼치고 싶을 때 가장 직접적인 기능이다. 대부분의 팀에서는 cone mode로 시작하고, 경로 지정은 set, 점진적 확장은 add, 상태 복구는 reapply, 전체 복원은 disable로 이해하면 된다.

새 저장소를 받는 시점이라면 git clone --sparse를 같이 고려할 수 있고, 네트워크 전송량까지 줄여야 한다면 partial clone 옵션을 별도로 검토하면 된다. 판단 기준은 작업 디렉터리를 줄이고 싶은지, object 전송량까지 줄이고 싶은지다.

참고 자료

• Git Documentation: git-sparse-checkout
• Git Documentation: git-clone
• Git Documentation: sparse-checkout