git clone –depthで、履歴を浅く取得する方法

​​Git​CI,コマンドライン

git clone --depth 1 <リポジトリ> を使うと、過去の履歴を取らずに、いちばん新しいコミットだけを取得できます。CI(GitHub Actions などのビルド)で毎回 clone するときや、履歴の長い大きなリポジトリを手早く手元に置きたいときに、ダウンロードする量とディスクの使用量を減らす方法です。このような履歴の一部だけを持つリポジトリを、Git では shallow(浅い)リポジトリと呼びます。あとから git fetch で履歴を足すことも、全部の履歴に戻すこともできます。検証環境でコマンドを実行し、操作の前と後の出力をそのまま載せています。

補足

検証環境は Ubuntu 24.04、Git 2.43.0 です。作者の名前とメールアドレスには例示用の値(Neko <neko@example.com>)を設定し、コミットの日時は環境変数で決めています。取り出し元のリポジトリ(neko-repo)は同じ検証環境の中に置き、そこから clone しました。GitHub などのサーバーから clone したときの動き、Windows と macOS での動作、サブモジュールを含むリポジトリ(--shallow-submodules)は試していません。

試したリポジトリと、ふつうに clone したときの大きさ

neko-repo には、main ブランチに5つのコミットがあります。どのコミットでも、圧縮の効かない約1MBのファイル photo.bin を別の中身に書き換えています。ほかに、4つ目のコミットから分かれた feature ブランチと、2つ目のコミットに付けたタグ v0.2 があります。

console
$ git log --oneline --all --graph
* 6992511 機能を追加
| * 599aee3 バージョン5
|/  
* 8189144 バージョン4
* d16bd65 バージョン3
* d7bc963 バージョン2
* ab65ff8 バージョン1

まず、--depth を付けずに clone しました。5つのコミットがすべて入り、.git フォルダーは 5.0M になりました。リモートのブランチ(origin/main と origin/feature)とタグも、すべて取得されています。

console
$ git clone --no-local neko-repo neko-full
Cloning into 'neko-full'...

$ git -C neko-full rev-list --count HEAD
5

$ git -C neko-full branch -r
  origin/HEAD -> origin/main
  origin/feature
  origin/main

$ git -C neko-full tag
v0.2

$ du -sh neko-full/.git
5.0M	neko-full/.git

git rev-list --count HEAD は、今のブランチからたどれるコミットの数を表示します。--no-local は、取り出し元をパスで指定しているので付けました。付けないとどうなるかは、次の節の囲みで示します。

–depth 1 で、最新のコミットだけを取得する

--depth 1 を付けて clone しました。git log に出るコミットは1つだけで、.git フォルダーは 1.2M になりました。手元に保存された pack ファイルの大きさを git count-objects -vH の size-pack で比べると、ふつうの clone の 4.77 MiB に対して 978.32 KiB でした。

console
$ git clone --depth 1 --no-local neko-repo neko-shallow
Cloning into 'neko-shallow'...

$ cd neko-shallow

$ git log --oneline
599aee3 バージョン5

$ git rev-list --count HEAD
1

$ du -sh .git
1.2M	.git

git clone の公式リファレンスによると、--depth は、指定した数のコミットまでで履歴を切った shallow clone を作るオプションです。

注意

取り出し元をパス(neko-repo や /path/to/repo など)で指定すると、--no-local を付けない限り --depth は効きません。検証環境で --no-local を付けずに試すと、次の警告が出て、5つのコミットがすべて取得されました。shallow にはなっていません。警告では、代わりに file:// で始まる URL で指定するよう案内されています。GitHub などの URL で指定するときは、この警告は関係ありません。

console
$ git clone -q --depth 1 neko-repo neko-local
warning: --depth is ignored in local clones; use file:// instead.

$ git -C neko-local rev-list --count HEAD
5

$ git -C neko-local rev-parse --is-shallow-repository
false

shallow リポジトリかどうかを確かめる

git rev-parse --is-shallow-repository で、今のリポジトリが shallow かどうかが分かります。git log の %d(ブランチ名などの表示)には grafted と出ました。

console
$ git rev-parse --is-shallow-repository
true

$ git log --decorate=short --format="%h %d %s"
599aee3  (grafted, HEAD -> main, origin/main, origin/HEAD) バージョン5

$ cat .git/shallow
599aee359ab0042ca3293d49ec6b2b1671ab2a16

.git/shallow には、取得した範囲のいちばん古いコミットの ID が書かれています。Git の shallow の設計メモによると、Git はこのファイルにあるコミットを、親のないコミットとして扱います。本当は親がいるのに、手元にはないためです。

手元にない履歴は、たどれない

shallow リポジトリでは、取得していないコミットを指定するとエラーになります。1つ前のコミット(HEAD~1)を指定すると、unknown revision(不明なリビジョン)というエラーになりました。

console
$ git log --oneline HEAD~1
fatal: ambiguous argument 'HEAD~1': unknown revision or path not in the working tree.
Use '--' to separate paths from revisions, like this:
'git <command> [<revision>...] -- [<file>...]'

git blame も、手元の最も古いコミットで止まります。version.txt は5回書き換えていますが、どの行も バージョン5 のコミットで書かれたように表示され、先頭に ^ が付きました。git show --stat でも、photo.bin が新しく追加されたファイル(Bin 0 -> 1000000 bytes)として表示されます。

console
$ git blame version.txt
^599aee3 (Neko 2026-11-05 10:00:00 +0900 1) v5

$ git show --stat --format="%h %s" HEAD
599aee3 バージョン5

 photo.bin   | Bin 0 -> 1000000 bytes
 version.txt |   1 +
 2 files changed, 1 insertion(+)

過去の変更を調べる作業(git log で履歴を追う、git blame で書いた人を探す、git bisect で原因のコミットを探すなど)をするときは、後の「あとから履歴を足す、減らす」の節の方法で、履歴を足してから行います。

–depth を付けると、ほかのブランチとタグが取れない

neko-shallow では、リモートのブランチは origin/main だけで、タグもありません。git fetch で取得するブランチの設定(remote.origin.fetch)も、main だけになっています。

console
$ git branch -r
  origin/HEAD -> origin/main
  origin/main

$ git tag

$ git config --get remote.origin.fetch
+refs/heads/main:refs/remotes/origin/main

これは、--depth が --single-branch を含むためです。公式リファレンスによると、--single-branch を付けると、1つのブランチの履歴だけを clone し、その後の git fetch でも、そのブランチだけを更新します。

ほかのブランチも浅く取りたいときは、--no-single-branch を付けます。どのブランチも先頭のコミットだけが取得され、タグ v0.2 のコミットも取得されました。

console
$ git clone -q --depth 1 --no-single-branch --no-local neko-repo neko-all

$ git -C neko-all branch -r
  origin/HEAD -> origin/main
  origin/feature
  origin/main

$ git -C neko-all log --oneline --all
6992511 機能を追加
599aee3 バージョン5
d7bc963 バージョン2

$ git -C neko-all tag
v0.2

main ではなく、決まった1つのブランチだけが必要なときは、--branch でブランチ名を指定します。

console
$ git clone -q --depth 1 --branch feature --no-local neko-repo neko-feature

$ git -C neko-feature log --oneline
6992511 機能を追加

$ git -C neko-feature branch -r
  origin/feature

あとから履歴を足す、減らす

ここからは、--depth 1 で clone した neko-shallow で試しました。git fetch に付けるオプションで、手元の履歴の長さを変えられます(git fetch の公式リファレンス)。

--deepen=2 は、今の手元のいちばん古いコミットから、さらに2つ前までを取得します。.git/shallow の ID も、新しくいちばん古くなった バージョン3 のコミットに変わりました。

console
$ git fetch -q --deepen=2

$ git log --oneline
599aee3 バージョン5
8189144 バージョン4
d16bd65 バージョン3

$ cat .git/shallow
d16bd65055e6c939231a960d0e4675610d8baae5

--depth は、ブランチの先頭から数えたコミットの数で、手元の履歴の長さを決め直します。今より少ない数(ここでは1)を指定すると、手元の履歴が短くなりました。

console
$ git fetch -q --depth=1

$ git log --oneline
599aee3 バージョン5

--shallow-since を使うと、数ではなく日時で範囲を決められます。11月3日の0時(日本時間)より後のコミットが取得されました。ここでは時刻とタイムゾーンまで書いて指定しています。

console
$ git fetch -q --shallow-since="2026-11-03 00:00 +0900"

$ git log --oneline
599aee3 バージョン5
8189144 バージョン4
d16bd65 バージョン3

–unshallow で、全部の履歴に戻す

git fetch --unshallow を実行すると、残りの履歴がすべて取得され、shallow ではなくなりました。.git/shallow も消えています。

console
$ git fetch -q --unshallow

$ git log --oneline
599aee3 バージョン5
8189144 バージョン4
d16bd65 バージョン3
d7bc963 バージョン2
ab65ff8 バージョン1

$ git rev-parse --is-shallow-repository
false

$ ls .git/shallow
ls: cannot access '.git/shallow': No such file or directory

ただし、取得するブランチの設定は main だけのままなので、feature ブランチは取れていません。git remote set-branches で、すべてのブランチ("*")を取得する設定に変えてから git fetch すると、origin/feature が出てきました。

console
$ git branch -r
  origin/HEAD -> origin/main
  origin/main

$ git config --get remote.origin.fetch
+refs/heads/main:refs/remotes/origin/main

$ git remote set-branches origin "*"

$ git fetch -q && git branch -r
  origin/HEAD -> origin/main
  origin/feature
  origin/main

CI で、浅い clone が使われていることがある

GitHub Actions で clone に使う actions/checkout は、README によると、標準では、ワークフローを動かすきっかけになったコミット1つだけを取得します。全部の履歴とブランチ、タグが必要なときは fetch-depth: 0 を指定する、と書かれています。CI の中で過去の履歴を使うコマンドを実行するときは、git rev-parse --is-shallow-repository で、浅い clone になっているかを確かめられます。

​Posted by 86