git archive: 저장소를 아카이브로 내보내기

지난 글에서 --stat으로 변경 규모를 요약해 보는 법을 다뤘다. 이번엔 저장소를 다루는 또 다른 실무 작업, 소스 내보내기다. 특정 버전의 소스 코드를 누군가에게 전달하거나 서버에 배포해야 할 때, git clone을 쓰면 .git 폴더에 담긴 전체 히스토리까지 통째로 따라온다. 받는 쪽은 커밋 기록이 필요 없는데도 무거운 .git을 떠안게 된다. git archive는 지정한 시점의 파일 스냅샷만 tar나 zip으로 깔끔하게 묶어 내보낸다.

핵심은 “버전 관리 메타데이터를 뺀, 순수한 소스 묶음”을 만든다는 점이다. 릴리즈 산출물, 배포 패키지, 코드 백업, 또는 빌드 서버에 소스를 넘길 때 적합하다.

기본 사용법

가장 단순한 형태는 트리(커밋·태그·브랜치)를 지정해 tar로 내보내는 것이다. 출력은 표준 출력으로 나오므로 파일로 저장하려면 리다이렉트하거나 -o를 쓴다.

# 현재 HEAD를 tar로 묶어 파일로 저장
git archive -o source.tar HEAD

# 특정 태그 버전을 내보내기
git archive -o release-1.0.tar v1.0

# 표준 출력으로 내보내 파이프로 연결
git archive HEAD | gzip > source.tar.gz

git archive는 작업 트리의 변경(스테이징 안 된 수정)이 아니라, 지정한 커밋에 기록된 내용을 내보낸다는 점을 기억하자. 즉 깨끗하고 재현 가능한 스냅샷을 보장한다.

포맷과 —prefix

출력 형식은 --format으로 정한다. tar, tar.gz, zip을 지원하며, 파일 확장자(-o foo.zip)로 자동 추론되기도 한다. 압축을 풀었을 때 모든 파일이 현재 디렉터리에 흩어지는 것을 막으려면 --prefix로 최상위 폴더를 붙인다.

# tar.gz + 최상위 폴더 이름 부여
git archive --format=tar.gz --prefix=app-1.0/ -o app-1.0.tar.gz v1.0

# zip 포맷
git archive --format=zip -o src.zip HEAD

# 지원 포맷 확인
git archive --list

--prefix=app-1.0/를 주면 압축 해제 시 모든 파일이 app-1.0/ 폴더 아래 정리되어, 흔히 보는 릴리즈 tarball 구조가 된다. 끝의 슬래시(/)를 빠뜨리면 폴더가 아니라 파일명 접두어가 되니 주의한다.

일부 경로만, 그리고 파일 제외하기

전체가 아니라 특정 하위 디렉터리만 내보낼 수도 있다.

git archive -o docs.tar HEAD docs/ src/public/

반대로, 아카이브에서 빼고 싶은 파일이 있다면 .gitattributes에 export-ignore 속성을 지정한다. 테스트 코드, CI 설정, 개발용 스크립트처럼 배포 산출물에 불필요한 항목을 제외할 때 유용하다.

# .gitattributes
tests/        export-ignore
.github/      export-ignore
*.dev.js      export-ignore

이렇게 지정하면 git archive로 만든 묶음에서 해당 경로가 빠진다. git clone이나 작업 트리에는 영향을 주지 않고, 오직 아카이브 산출물에만 적용된다는 점이 핵심이다. 비슷하게 export-subst 속성으로 파일 안에 커밋 정보(예: 버전 해시)를 치환해 넣을 수도 있다.

원격 저장소에서 바로 받기

로컬에 클론하지 않고 원격 저장소에서 직접 아카이브를 받을 수도 있다. 단, 서버가 이 기능을 허용해야 한다(많은 호스팅은 보안상 제한한다).

git archive --remote=ssh://git@host/repo.git --format=tar.gz -o app.tar.gz v1.0

GitHub 같은 호스팅은 git archive --remote 대신, 태그·릴리즈마다 자동 생성되는 소스 tarball/zip 다운로드 링크를 제공하므로 그쪽을 쓰는 편이 일반적이다.

정리하면, “히스토리는 빼고 특정 버전의 파일만 깔끔하게” 필요할 때 git archive가 정답이다. --prefix로 폴더 구조를 잡고, export-ignore로 배포에 불필요한 파일을 솎아내면, 릴리즈 파이프라인에 바로 끼워 넣을 수 있는 재현 가능한 산출물이 만들어진다. 빌드 시스템에서 git archive로 소스를 추출해 패키징하는 패턴은 지금도 널리 쓰인다.

---

지난 글: git diff —stat: 변경 요약 한눈에 보기

읽어주셔서 감사합니다. 😊