修正済みのファイルを、もう一度直そうとしました — 浅い永続クローンの陳腐化と「読む前に取り直す」判断

なぜ浅い永続クローンは黙って古くなるのか

速度のために --depth 1 の浅いクローンを使い回す運用には、はっきりした利点があります。毎回フルクローンするより圧倒的に速く、ディスクも軽い。私のクローンも node_modules を持たない構成で 30MB ほどに収まっていて、再利用したくなる気持ちは自然です。

問題は、その浅いクローンが「最新だと錯覚しやすい」ことです。古くなる経路はいくつもあります。

1. 別のセッション・別のマシンが先に push している。 自動運用を分散していると、同じリポジトリに複数の書き手がいます。自分が眠っている間にリモートは進みます。
2. pull が走らなかった、あるいは握りつぶされた。 リベース衝突やネットワークの瞬断で pull が中途半端に終わっても、後続の処理は何事もなく走り続けることがあります。
3. 浅い履歴ゆえに pull の挙動が読みにくい。 --depth 1 のローカルは履歴をほとんど持たないため、リベースが期待通りに進まない場面が増えます。

どれも派手なエラーを出しません。だから「黙って古くなる」のです。そして無人運用では、その沈黙を疑う人間がその場にいません。

陳腐化を数値で見る — ローカル HEAD と リモート HEAD を突き合わせる

対策の核心は、「pull が成功したかどうか」ではなく「いま読んでいる木が、リモートから何コミット遅れているか」を数値で出すことです。ネットワーク越しに参照だけ取ってくる git ls-remote を使えば、フェッチせずに先頭コミットを確認できます。

まず、避けたかった素朴な書き方です。

# Before: pull が成功したと信じて、そのまま判断に進む
cd "$WORK"
git pull --rebase origin main   # 失敗しても後続は止まらないことがある
# ここで content/ を読んで「まだ無い」と判断 → 古い木で誤判断

次に、判断の前に遅れを測る書き方です。フェッチ前にリモート先頭を取り、ローカルと突き合わせます。

# After: 判断の前に、リモートとの遅れをコミット数で出す
cd "$WORK"
LOCAL=$(git rev-parse HEAD)
REMOTE=$(git ls-remote origin -h refs/heads/main | cut -f1)
 
if [ "$LOCAL" != "$REMOTE" ]; then
  # どれだけ遅れているかを数える（浅い履歴では取得できないこともある）
  git fetch --depth 50 origin main 2>/dev/null
  BEHIND=$(git rev-list --count "HEAD..$REMOTE" 2>/dev/null || echo "unknown")
  echo "stale: local=$LOCAL remote=$REMOTE behind=$BEHIND"
fi

ここで大事なのは、ls-remote が作業ツリーを一切変えない点です。読み取りの鮮度を、読み取りの判断を汚さずに測れます。LOCAL != REMOTE が出た時点で、いまの木は判断の土台として信用できない、と機械的に分かります。

取り直すか、追従するか — 判断の分かれ目

遅れが分かったら、次は「どう追いつくか」です。ここは一律ではなく、その読み取りが何を駆動するかで選びます。

私はこうしてたどり着いた基準を、いまも使い続けています。基準は単純です。その読み取りが「これから何をするか」を決めるなら、迷わず取り直す。 表示や集計のような、間違っても後で直せる読み取りなら追従で十分です。判断を駆動する読み取りだけ、鮮度に厳しくする。これで取り直しの回数を抑えつつ、誤判断の芽を摘めます。

/tmp の浅いクローンが所有者違いで消せない、といった付随トラブルにぶつかることもあります。その場合は固執せず、書き込める別のパスへ新規クローンしてしまうのが結局いちばん速いです。鮮度と所有権の問題を、取り直し一回でまとめて解消できます。

二重作業を防ぐのは「冪等性」

鮮度の検知は、二重作業を防ぐ仕組みの半分でしかありません。残り半分は、生成そのものを冪等にすることです。つまり「すでに片付いているなら、何もしない」を、生成の直前に実体で確かめます。

# 生成の前に、成果物が既に存在するかを実体で確認する
TARGET="content/articles/ja/${CAT}/${SLUG}.mdx"
if [ -f "$TARGET" ]; then
  echo "skip: $SLUG は既に存在します（二重生成を回避）"
  exit 0
fi
# ここから先は「本当にまだ無い」ことが保証された状態

地味ですが、これがあると鮮度検知をすり抜けた取りこぼしも止まります。鮮度の検知は「古い土台で考え始めること」を防ぎ、冪等性のチェックは「同じ成果物を二度作ること」を防ぐ。役割が違うので、両方あって初めて安心できます。今回の二重修正も、この実体確認が生成の前にあれば、古い木を読んでいたとしても最後の一歩で止まっていました。

運用に組み込む — 判定関数とログ

最後に、ここまでを一つの判定にまとめます。無人で走る前提なので、判断の根拠は必ずログに残します。後から「なぜ取り直したのか」を人間が追えることが、無人運用の安心につながります。

# refresh_if_stale: 判断の前に呼ぶ。古ければ true を返す
refresh_if_stale() {
  local work="$1" remote_url="$2"
  cd "$work" || return 1
  local local_sha remote_sha
  local_sha=$(git rev-parse HEAD)
  remote_sha=$(git ls-remote "$remote_url" -h refs/heads/main | cut -f1)
  if [ "$local_sha" = "$remote_sha" ]; then
    echo "[fresh] $(TZ=Asia/Tokyo date +%H:%M) local==remote ${local_sha:0:7}"
    return 1
  fi
  echo "[stale] local=${local_sha:0:7} remote=${remote_sha:0:7} -> 取り直し"
  return 0
}
 
# 呼び出し側
if refresh_if_stale "$WORK" "$REMOTE_URL"; then
  # 判断を駆動する読み取りの前にだけ取り直す
  rm -rf "$WORK" && git clone --depth 1 "$REMOTE_URL" "$WORK"
fi

TZ=Asia/Tokyo を明示しているのは、ログの時刻が UTC に振れて前日の記録を上書きしてしまう事故を避けるためです。これも無人運用で一度痛い目を見て、以来かならず付けるようにしました。判定そのものは数行ですが、「鮮度を疑う場所を決めておく」という設計の意思が、二重作業や誤判断を未然に止めてくれます。

次の一歩としては、いま動かしている無人処理を一つ選び、「判断を駆動する読み取り」がどこかを書き出してみてください。そこにだけ refresh_if_stale を一段かませる。たいていは関数一つで、静かな誤判断の経路をまるごと塞げます。お読みいただきありがとうございました。