自分の Web サイトのリポジトリで、ある関数の挙動がいつ変わったのかをエージェントに調べてもらっていた午後のことです。返ってきた答えは「このファイルは直前のコミットで新規作成されています。それ以前の履歴はありません」でした。
そのファイルは、何か月も前から少しずつ書き足してきたものです。手元の iMac で git log を引くと、二十回近い変更がきちんと並んでいます。
原因は、作業コピーを git clone --depth 1 で用意していたことでした。時間を節約するつもりで選んだ浅い clone が、エージェントにとっては「履歴の一部しか無い世界」になっていたのです。しかも git は、多くの場面でそれをエラーとして教えてくれません。
4 通りの clone で、同じリポジトリを取り直しました
どこまで差が出るのかを確かめるため、同じリポジトリ(Next.js のサイト・コミット 2,434 件)を 4 通りで clone し、時間と .git の大きさを記録しました。Linux の作業環境・git 2.34.1 で、各 2 回の値です。
| 方式 | オプション | clone 時間 | .git の大きさ | 手元のコミット数 |
|---|---|---|---|---|
| shallow | --depth 1 | 2.79 秒/2.81 秒 | 18MB | 1 |
| blobless | --filter=blob:none | 4.54 秒/4.47 秒 | 21MB | 2,434 |
| treeless | --filter=tree:0 | 3.98 秒/4.00 秒 | 18MB | 2,434 |
| 通常 | (なし) | 10.20 秒/10.14 秒 | 39MB | 2,434 |
速さだけを見れば、shallow がいちばんです。通常の clone の 4 分の 1 ほどで終わります。私が最初に shallow を選んだのも、この差に惹かれたからでした。
計測に使ったスクリプトは次のとおりです。お手元のリポジトリの URL に差し替えれば、そのまま同じ表を作れます。
#!/usr/bin/env bash
# clone 方式ごとの所要時間と .git の大きさを並べる
set -u
URL="${1:?リポジトリの URL を渡してください}"
WORK="$(mktemp -d)"
cd "$WORK"
for mode in "shallow:--depth 1" "blobless:--filter=blob:none" "treeless:--filter=tree:0" "full:"; do
name="${mode%%:*}"; opts="${mode#*:}"
start=$(date +%s.%N)
# treeless は後の操作で固まることがあるため、clone 自体にも上限をかける
timeout 300 git clone -q $opts "$URL" "$name" || { echo "$name: clone 失敗"; continue; }
end=$(date +%s.%N)
printf "%-9s %6.2fs .git=%sMB commits=%s\n" "$name" "$(echo "$end - $start" | bc)" \
"$(du -sm "$name/.git" | cut -f1)" "$(git -C "$name" rev-list --count HEAD)"
done
echo "作業ディレクトリ: $WORK"timeout を挟んでいるのは、次の節で触れる treeless の振る舞いに一度つかまったからです。
エージェントがよく打つ 5 つのコマンドで、答えを比べました
clone の速さより大事なのは、そのあとエージェントが履歴を尋ねたときに正しい答えが返るかでした。調査や修正の途中でエージェントがよく打つコマンドを 5 つ選び、4 つの作業コピーで同じように実行しました。対象は、冒頭で「新規作成」と言われたファイルです。
| コマンド | shallow | blobless | treeless | 通常 |
|---|---|---|---|---|
git log --oneline -20 | 1 件だけ | 20 件 | 20 件 | 20 件 |
git diff --stat HEAD~5 | fatal(HEAD~5 が無い) | 0.63 秒 | 1.11 秒 | 0.17 秒 |
git log -- ファイル | 1 件(誤り) | 19 件・0.04 秒 | 90 秒で打ち切り | 19 件・0.04 秒 |
git blame ファイル | 234 行すべてが 1 コミット | 5 コミット・1.70 秒 | (未計測) | 5 コミット・0.03 秒 |
git log -p -3 -- ファイル | 全行が「新規追加」 | 正しい差分 | (未計測) | 正しい差分 |
この表で私の手が止まったのは、shallow の列です。エラーで止まってくれたのは git diff HEAD~5 の 1 行だけで、残りの 4 つは何事もなかったかのように、誤った答えを返しました。
git blame では、234 行すべての先頭に ^ が付いていました。これは「このコミットより前は手元に無い」という境界の印なのですが、出力を読むエージェントにとっては、ただの 1 文字にすぎません。git log -p では、ファイル全体が new file mode 100644 として表示されます。エージェントが「直前に新規作成された」と判断したのは、むしろ素直な読み方だったのです。
treeless の列にも落とし穴がありました。ファイルを指定した git log が、コミットごとに木構造を一つずつ取りに行くため、90 秒待っても終わりませんでした。エージェントのターミナルがいつまでも「実行中」のまま返ってこないとき、この形を一度疑ってみる価値があると思います。
あとから深くする操作も試しました
浅く取ってしまった作業コピーを、あとから直せるかも確かめました。
| 操作 | 時間 | 結果 |
|---|---|---|
git fetch --deepen=50 | 0.77 秒 | HEAD~5 の diff は通るようになりました。ただし対象ファイルの blame は、まだ全行が境界コミットのままでした |
git fetch --unshallow | 9.69 秒 | 2,434 件すべてがそろい、blame も正しくなりました。.git は 51MB で、最初から通常の clone をした場合(39MB)より大きくなりました |
--deepen=50 は、直近 50 コミットの範囲で答えを正しくしてくれます。一方で、変更が 50 コミットより前にあるファイルについては、相変わらず誤った blame を返します。「少し深くしたから大丈夫」とは言えないのです。
--unshallow は確実ですが、時間は通常の clone とほぼ同じで、容量はかえって増えました。結局、最初の数秒を惜しんだぶんを、あとで同じだけ払い直すかたちになります。
用途ごとの線引きと、浅さを先に確かめる仕組み
この計測を経て、私は作業コピーの取り方を用途で分けるようにしました。原則にすると、次の一文になります。
速さは clone で稼ぎ、履歴の質問は浅い作業コピーにさせない。
| エージェントに頼む作業 | 選んでいる clone |
|---|---|
| ビルド・テスト・最新コードの小さな修正 | shallow(--depth 1) |
| 「いつ・なぜ変わったか」の調査、blame、リグレッション探し | blobless(--filter=blob:none) |
| bisect や大量のファイル履歴をなめる作業 | 通常の clone |
treeless(--filter=tree:0) | エージェント用には使わない |
blobless は、clone が通常の半分ほどの時間で済み、履歴の答えも正しく返ります。blame のたびに中身を取りに行くぶん 1〜2 秒かかりますが、誤った答えに比べればはるかに安いと感じています。
もう一つ、作業コピーが浅いかどうかを、履歴系のコマンドの前に確かめる短いスクリプトを置きました。エージェントへの指示ファイルに「履歴を調べる前にこれを実行し、SHALLOW と出たら答えを出さずに報告すること」と書き添えています。
#!/usr/bin/env bash
# history-check.sh — 履歴を尋ねる前に、作業コピーの浅さと欠けを確かめる
set -eu
if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then
echo "SHALLOW: 手元のコミットは $(git rev-list --count HEAD) 件だけです"
echo " blame / log -- <file> / log -p の答えは信用できません"
echo " 対処: git fetch --unshallow(または blobless で取り直す)"
exit 2
fi
filter="$(git config --get remote.origin.partialclonefilter || true)"
case "$filter" in
tree:*) echo "TREELESS: ファイル指定の log が長時間止まることがあります"; exit 3 ;;
blob:none) echo "BLOBLESS: 履歴は正しく読めます(blame は初回だけ数秒かかります)" ;;
*) echo "FULL: 制限はありません" ;;
esacここで exit 2 と exit 3 を分けているのは、エージェントが終了コードだけで次の手を選べるようにするためです。標準出力の文面は言い回しが変わっても、終了コードなら条件分岐に使えます。
git rev-parse --is-shallow-repository は、浅い clone で true を返します。partial clone の種類は remote.origin.partialclonefilter に記録されるので、そこを読めば blobless か treeless かも分かります。
一歩引いて考えたこと
エージェントは、渡された世界の中ではとても誠実に推論します。境界の印 ^ を見落としたのは、エージェントの不注意というより、「履歴の一部しか無い」という前提を私が伝えていなかったからでした。
道具の速さを選ぶとき、その代わりに何が見えなくなるのか——そこまでを含めて渡すのが、任せる側の仕事なのだと思います。
まずはお手元の作業コピーで git rev-parse --is-shallow-repository を一度打ってみていただければ幸いです。true が返ってきたら、最近エージェントが答えた「履歴の話」を一つだけ見直してみてください。冒頭の「新規作成」も、そうして見直したことで気づけたものでした。
/boost のような使い捨ての作業領域で何が欠けるかは「/boost が「検証済み」と返してきたとき、その worktree に何が無かったのかを先に数えています」に書き残しています。読み取り専用の .git をエージェントへ渡すときの設計と費用の比べ方は、「同じ履歴を読むのに 38 秒と 0.4 秒 — 読み取り専用になった .git をエージェントへどう渡すか」でもう一段深く扱っています。