git sparse-checkout 명령이 없는 구버전 git에서 폴더 하나만 받을 때 (core.sparseCheckout)

여러 서비스를 한 저장소에 모아둔 상태에서, 오래된 서버의 구버전 git 으로 필요한 폴더만 골라 받는 방법입니다.

서비스 여러 개를 저장소 하나로 합친 뒤, 배포 서버에서는 자기 서비스 폴더만 받아서 빌드하게 하려고 했습니다. 요즘 git 이라면 git sparse-checkout 명령 한 줄이면 되는 일입니다.

그런데 배포 서버에서 실행해 보니 그런 명령이 없다는 오류가 났습니다. 오래된 서버라 git 버전이 낮았고, 이 명령은 2.25 버전에서 처음 생긴 것이었습니다.

git 을 올리면 간단하지만, 폐쇄망이거나 여러 서비스가 같이 쓰는 서버는 패키지 하나 올리는 것도 쉽지 않습니다. 다행히 명령만 없을 뿐 기능 자체는 훨씬 전부터 있어서, 설정 파일로 같은 결과를 낼 수 있었습니다.

- git sparse-checkout 명령은 2.25 에서 생겼지만, 기능은 그 전부터 있었다

- core.sparseCheckout 설정 + .git/info/sparse-checkout 파일로 같은 일을 한다

- 폴더를 바꿀 때는 git read-tree -mu HEAD 로 다시 반영한다

- 받는 폴더만 줄어들 뿐 내려받는 양은 그대로라, 필요하면 --depth 1 을 같이 쓴다

1. 증상

구버전 git 에서 git sparse-checkout 을 실행하면 이렇게 나옵니다.

sparse-checkout 이 git 명령이 아니라는 뜻입니다. 오타가 아니라 그 버전에 명령 자체가 없는 것이라, 옵션을 바꿔봐도 소용이 없습니다.

2. 명령 없이 설정으로 하기

git sparse-checkout 명령은 사실 원래 있던 설정을 편하게 다루는 도구입니다. 구버전에서는 그 설정을 직접 하면 됩니다.

- 저장소에 sparse checkout 을 켠다 (core.sparseCheckout true)

- .git/info/sparse-checkout 파일에 받을 폴더를 적는다

- 그 상태로 체크아웃하면 적힌 폴더만 작업 폴더에 풀린다

순서가 중요합니다. git clone 을 먼저 하면 그 순간 전체가 풀려버리니, 빈 저장소를 만들고 설정부터 한 뒤 받아와야 합니다.

파일에 적는 형식은 .gitignore 와 비슷합니다. 앞에 / 를 붙이면 저장소 최상위 기준이고, 끝에 / 를 붙이면 폴더라는 뜻입니다. 여러 줄을 적으면 여러 폴더를 같이 받습니다.

3. 받을 폴더를 바꾸거나 늘릴 때

나중에 폴더를 추가하려면 파일을 고친 뒤 git read-tree -mu HEAD 를 실행합니다. 지금 커밋을 기준으로 작업 폴더를 다시 맞추라는 명령이라, 새로 적은 폴더는 풀리고 지운 폴더는 사라집니다.

파일만 고치고 이 명령을 안 치면 아무 변화가 없어서, 설정이 안 먹는다고 착각하기 쉽습니다. 다음 pull 때 반영되기도 하지만 바로 확인하려면 이 명령을 쓰는 게 확실합니다.

4. 받는 양은 줄지 않는다

여기서 흔히 오해하는 부분이 있습니다. sparse checkout 은 작업 폴더에 풀리는 파일만 줄여줄 뿐, 저장소 데이터는 전부 내려받습니다. .git 폴더 크기는 그대로입니다.

- 배포 서버 디스크나 받는 시간이 부담이면 --depth 1 로 최신 커밋 하나만 받는다

- 새 git 에는 받는 양까지 줄이는 기능(--filter)이 있지만, 서버 쪽 지원도 필요해서 구버전 환경에선 기대하기 어렵다

- 빌드만 하는 서버라면 이력이 필요 없으니 --depth 1 로 충분한 경우가 많다

5. 젠킨스에서 쓸 때

젠킨스의 Git 플러그인에도 같은 기능이 Sparse Checkout paths 라는 옵션으로 들어 있지만, 저는 이 옵션 대신 빌드 스텝 맨 앞에서 위 명령을 직접 실행했습니다. 소스 관리 설정은 그대로 두니 태그를 고르는 파라미터나 자격증명도 손댈 필요가 없었습니다.

- 소스 관리(Git)는 기존 설정 그대로 두고 저장소 전체를 받는다

- 첫 빌드 스텝에서 core.sparseCheckout 을 켜고 서비스 폴더 하나만 적는다

- git read-tree -mu HEAD 로 나머지 폴더를 작업 공간에서 걷어낸다

- 빌드와 배포 경로는 서비스폴더/ 아래를 보도록 한 칸씩 바꾼다

한 가지 알아둘 점은 이 설정이 작업 공간에 남는다는 것입니다. 다음 빌드부터는 플러그인이 소스를 받는 단계에서 이미 폴더가 걸러진 채로 풀리는데, 동작에는 문제가 없고 오히려 빌드가 조금 가벼워집니다. 다만 나중에 이 잡에서 다른 폴더가 필요해지면 목록 파일부터 고쳐야 한다는 걸 기억해 두는 게 좋습니다.

6. 정리

명령이 없다는 오류가 나면 git 을 올려야 하나 싶지만, 오래된 기능이 새 명령으로 포장만 바뀐 경우가 꽤 있습니다.

- git sparse-checkout 은 2.25 부터, 기능 자체는 그 전부터 있다

- 빈 저장소에서 core.sparseCheckout 을 켜고 폴더 목록을 적은 뒤 받는다

- 목록을 바꾸면 git read-tree -mu HEAD 로 반영한다

- 받는 양은 그대로라 --depth 1 을 같이 쓴다

- 젠킨스는 빌드 스텝 맨 앞에서 같은 명령을 실행하면 된다

서버의 git 을 올릴 수 있다면 그게 제일 편하지만, 그럴 수 없는 환경이라면 설정 두 줄로 충분히 같은 결과를 낼 수 있습니다.

여기까지 구버전 git 에서 폴더 하나만 받는 방법에 대해서 작성해봤습니다. 여기까지 읽어주셔서 감사합니다!