git archive

git archive は、指定したコミット・ブランチ・タグのスナップショットを ZIP や tar.gz などの形式でエクスポートするコマンドです。

tar や zip コマンドと違い、.gitattributes の設定を尊重してビルド成果物や不要ファイルを除外できるため、クリーンなリリース配布物の作成に適しています。

入門者向けメモ: git export というコマンドは Git には存在しません。ファイルをエクスポートしたいときは git archive を使います。

基本的な使い方

# HEAD のスナップショットを ZIP ファイルに出力する
git archive --format=zip HEAD -o release.zip

# 特定のタグ（v1.0.0）を tar.gz で出力する
git archive --format=tar.gz v1.0.0 -o v1.0.0.tar.gz

# パイプを使って gzip 圧縮する（--format=tar のデフォルト）
git archive v1.0.0 | gzip > v1.0.0.tar.gz

プレフィックス（ディレクトリ名）を付ける

アーカイブを展開したとき、すべてのファイルがトップレベルに展開されると扱いにくいことがあります。--prefix を使うと展開後のディレクトリ名を指定できます。

# 展開後に myproject-1.0/ ディレクトリが作られる
git archive --prefix=myproject-1.0/ v1.0.0 -o myproject-1.0.tar.gz

# 展開後の確認
tar tzf myproject-1.0.tar.gz | head -5
# myproject-1.0/
# myproject-1.0/README.md
# myproject-1.0/src/
# ...

特定のディレクトリだけをアーカイブする

ツリーの一部だけを含めたい場合は、<tree-ish> の後にパスを指定します。

# src/ ディレクトリだけをアーカイブ
git archive --format=zip HEAD src/ -o src-only.zip

.gitattributes でファイルを除外する

.gitattributes に export-ignore 属性を設定すると、アーカイブから特定のファイルやディレクトリを除外できます。テストファイルや CI 設定など、配布物に含めたくないものを除外するのに使います。

# .gitattributes に追記
echo "tests/ export-ignore" >> .gitattributes
echo ".github/ export-ignore" >> .gitattributes
echo ".gitignore export-ignore" >> .gitattributes

git add .gitattributes && git commit -m "アーカイブ除外設定を追加"

# .gitattributes の例
tests/         export-ignore
.github/       export-ignore
.gitignore     export-ignore
docs/          export-ignore
Makefile       export-ignore

その後アーカイブを作成すると、これらのファイルは含まれません。

git archive --format=zip v1.0.0 -o release.zip

export-subst：アーカイブ内でバージョン情報を埋め込む

.gitattributes の export-subst を使うと、アーカイブ作成時にファイル内の $Format:...% プレースホルダーを Git の情報で置換できます。

# .gitattributes
version.txt export-subst

# version.txt
Version: $Format:%describe%$
Commit: $Format:%H$
Date: $Format:%ci$

アーカイブを展開すると version.txt の内容がコミット情報で置換されます。

リモートリポジトリから直接取得する

ローカルにリポジトリをクローンせずに、リモートから直接アーカイブを取得することもできます（サーバー側で uploadarchive が許可されている場合のみ）。

git archive --remote=git@github.com:user/repo.git v1.0.0 -o repo-v1.0.0.tar.gz

CI/CD でのリリース配布例

GitHub Actions でタグをプッシュしたときに自動でリリースアーカイブを作成する例です。

# .github/workflows/release.yml
name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: アーカイブを作成
        run: |
          VERSION="${GITHUB_REF_NAME}"
          git archive \
            --format=tar.gz \
            --prefix="myproject-${VERSION}/" \
            "${VERSION}" \
            -o "myproject-${VERSION}.tar.gz"

      - name: GitHub Releases にアップロード
        uses: softprops/action-gh-release@v2
        with:
          files: myproject-*.tar.gz

tar / zip コマンドとの違い

比較項目	git archive	tar / zip
.git/ の除外	自動で除外される	手動で --exclude=.git が必要
export-ignore の適用	サポート	非対応
特定コミットのスナップショット	簡単に指定可能	別途チェックアウトが必要
リモートから直接取得	--remote で可能	非対応

ヒント

• --format を省略すると tar 形式になります。zip が必要な場合は明示してください。
• GitHub や GitLab はリポジトリ画面から ZIP をダウンロードできますが、内部では git archive と同じ仕組みを使っています。
• .gitattributes の設定は git archive 実行時にコミット済みのものが使われます（未コミットの変更は反映されません）。