Git bundle 사용법

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

git bundle은 Git 저장소의 객체와 ref 정보를 하나의 파일로 묶어 옮길 때 쓰는 명령입니다. 원격 서버에 바로 접근할 수 없는 환경에서 저장소를 전달하거나, 특정 시점의 저장소 상태를 파일로 보관할 때 기준을 잡기 좋습니다.

핵심은 bundle이 일반 압축 파일이 아니라 Git이 읽을 수 있는 전송용 묶음이라는 점입니다. git clone, git fetch, git ls-remote는 bundle 파일을 읽을 수 있지만, bundle 파일로 git push하는 방식은 지원하지 않습니다.

git bundle은 무엇을 담을까

공식 Git 문서 기준으로 bundle은 pack 파일에 헤더를 더한 형식입니다. pack에는 Git 객체가 들어가고, 헤더에는 bundle 안에 어떤 ref가 있는지와 필요한 선행 커밋 정보가 들어갑니다.

그래서 bundle은 저장소를 통째로 zip으로 압축한 파일과 다릅니다. 작업 트리의 임시 파일이나 무시된 파일을 보관하는 목적이 아니라, Git 객체 데이터베이스와 ref를 다른 저장소가 읽을 수 있게 옮기는 목적에 가깝습니다.

git bundle create repo.bundle --all
git bundle verify repo.bundle
git clone repo.bundle repo-copy

위 흐름은 저장소 전체를 bundle로 만들고, 읽을 수 있는지 검증한 뒤, 새 디렉터리로 clone하는 기본 예입니다. --all은 모든 ref에서 도달 가능한 객체를 포함하는 방식으로 이해하면 됩니다.

언제 쓰면 좋을까

git bundle은 네트워크 서버를 대신하는 영구 원격 저장소가 아닙니다. 파일 하나로 전달하고 읽는 용도에 강합니다. 따라서 일회성 전달, 오프라인 환경, 폐쇄망 반입, 단순 백업에 적합합니다.

상황	적합한 선택	이유
새 환경에 저장소를 한 번 전달	git bundle	파일 복사만으로 clone 또는 fetch 가능
계속 협업하며 양방향 동기화	일반 Git 원격 저장소	bundle은 push 대상이 아니며 수동 전달이 필요
큰 저장소 clone 속도 보조	--bundle-uri 또는 서버 광고 bundle URI	원격 fetch 전에 객체를 미리 받을 수 있음
소스 외 산출물까지 보관	별도 백업 도구	Git이 추적하지 않는 파일은 bundle 대상이 아님

무난한 기준은 간단합니다. Git 이력 자체를 옮기는 목적이면 bundle을 검토하고, 작업 디렉터리 전체 백업이나 운영 파일 보관이 목적이면 다른 백업 방식을 함께 써야 합니다.

전체 bundle과 증분 bundle은 어떻게 다를까

bundle은 self-contained 형태로 만들 수도 있고, 특정 커밋이나 ref를 제외한 증분 형태로 만들 수도 있습니다. 받는 쪽이 아무 이력도 없는 상태라면 전체 bundle이 필요합니다. 이미 같은 기반 이력을 갖고 있다면 증분 bundle로 전달량을 줄일 수 있습니다.

git bundle create full.bundle --all
git bundle create update.bundle main ^v1.0.0
git bundle verify update.bundle

두 번째 예시는 main에서 도달 가능하지만 v1.0.0에서 도달 가능한 객체는 제외하는 식의 증분 bundle입니다. 이 경우 받는 저장소에 제외 기준이 되는 이력이 있어야 합니다. git bundle verify는 현재 저장소가 bundle을 적용할 수 있는지 확인하는 데 유용합니다.

증분 bundle을 만들 때 가장 흔한 실수는 받는 쪽에 없는 기반 커밋을 제외하는 것입니다. 그 상태에서는 bundle 안의 객체만으로 이력을 완성할 수 없으므로 fetch나 unbundle 단계에서 실패할 수 있습니다.

 

 

bundle에서 가져올 때 무엇을 확인할까

bundle 파일은 repository 인자처럼 읽을 수 있습니다. 새 저장소를 만들 때는 git clone을 쓰고, 이미 있는 저장소에 ref와 객체를 가져올 때는 git fetch를 씁니다.

git clone repo.bundle repo-copy
git fetch repo.bundle main:refs/heads/from-bundle
git ls-remote repo.bundle

git ls-remote로 bundle 안에 어떤 ref가 들어 있는지 먼저 확인할 수 있습니다. 기존 저장소에 가져올 때는 원격 브랜치 이름을 바로 덮어쓰지 않도록 별도 브랜치 이름으로 받아 검토하는 편이 안전합니다.

bundle은 파일이므로 전달 경로의 무결성도 별도로 고려해야 합니다. Git 차원에서는 객체 해시와 bundle 검증이 있지만, 파일 전달 과정에서 잘못된 파일을 받지 않도록 체크섬이나 서명 정책을 함께 쓰는 환경도 있습니다.

--bundle-uri는 같은 기능일까

git clone --bundle-uri=<uri>는 clone 전에 지정한 URI에서 bundle을 받아 로컬 저장소에 먼저 풀어 넣는 옵션입니다. 이후 원격 저장소에서 남은 객체와 최신 ref를 가져오는 흐름입니다.

공식 git clone 문서 기준으로 이 옵션은 bundle 안의 ref를 숨겨진 refs/bundle/* namespace에 저장합니다. 또한 --depth, --shallow-since, --shallow-exclude와 함께 쓸 수 없습니다.

git clone --bundle-uri=https://example.com/project.bundle https://example.com/project.git

bundle-uri 문서는 큰 저장소의 clone과 fetch를 빠르게 만들거나 원본 서버 부하를 줄이는 목적을 설명합니다. 서버가 protocol v2 capability로 bundle URI를 광고할 수도 있고, 사용자가 명령행에서 직접 URI를 지정할 수도 있습니다.

안전한 사용 기준

첫째, 전달 목적이 전체 이력인지 증분 업데이트인지 먼저 정합니다. 새 환경으로 처음 옮긴다면 전체 bundle이 단순합니다. 이미 같은 기반 이력이 있는 저장소에 추가분만 전달한다면 증분 bundle이 맞습니다.

둘째, 받는 쪽에서 git bundle verify 또는 git ls-remote로 먼저 확인합니다. 특히 증분 bundle은 필요한 선행 커밋이 없으면 적용할 수 없으므로, 곧바로 중요한 브랜치에 fetch하지 않는 편이 안전합니다.

셋째, bundle을 장기 백업으로 쓸 때는 Git이 추적하는 객체만 들어간다는 점을 명확히 해야 합니다. 빌드 산출물, 로컬 설정, 무시된 파일, 외부 데이터는 별도 백업 범위로 다뤄야 합니다.

자주 묻는 질문

bundle 파일에 push할 수 있을까

아닙니다. 공식 문서는 bundle 파일에서 clone, fetch, ls-remote처럼 읽는 동작은 가능하지만 bundle로 push하는 쓰기 동작은 지원하지 않는다고 설명합니다.

bundle은 bare 저장소와 같을까

같지 않습니다. bare 저장소는 Git 저장소 디렉터리 형태이고, bundle은 Git 객체와 ref 정보를 담은 단일 파일입니다. 전달과 보관에는 bundle이 간단하지만, 협업 원격 저장소 역할은 bare 저장소나 Git 서버가 더 적합합니다.

증분 bundle은 언제 실패할까

받는 저장소에 필요한 선행 커밋이 없으면 실패할 수 있습니다. 증분 bundle은 제외한 이력을 받는 쪽이 이미 갖고 있다는 전제에서 크기를 줄이는 방식이기 때문입니다.

정리

git bundle은 Git 이력을 파일 하나로 옮기는 기능입니다. 전체 bundle은 새 clone이나 단순 보관에 적합하고, 증분 bundle은 이미 기반 이력을 공유하는 저장소 사이에서 전달량을 줄이는 데 적합합니다.

실무 기준은 세 가지입니다. 먼저 전체 전달인지 증분 전달인지 정합니다. 받는 쪽에서는 적용 전에 verify와 ref 목록을 확인합니다. 지속적인 협업이나 양방향 동기화가 필요하면 bundle 대신 일반 Git 원격 저장소를 사용합니다.