referenceupdated v2growing

Git submodule 運用ガイド — 何がいつ更新されるのか

submodule を含むリポジトリで「何をしたら何が更新されるか」を表で整理。親ポインタと submodule 実体の分離を理解し、意図しないポインタ更新を避ける。

現状(2026-10-02): 本リポジトリ(Parlourite Notes)では agents/methodology の submodule を廃止した。 Cloudflare Pages が private submodule を認証なしで clone できず、clone 段階でビルドが失敗するため (→ agents/methodology を submodule から通常ファイルへ移す)。実体は通常ファイルとして本リポジトリで追跡している。 この記事の submodule 一般則は、submodule を使い続ける他リポジトリ(例: Parlourite)向けとして読むこと。 本リポジトリでの方法論の更新は、submodule ではなく実体のコピーで行う。

この記事でやりたいこと

  • submodule(例: agents/methodology)を含むリポジトリで、日常作業と submodule 更新を安全に分けたい
  • 「どの操作で何が更新されるのか」を即座に引ける一覧がほしい
  • git add -A の何が危険で、どう回避するかを知りたい

コマンド早見表

親リポジトリのルートから

やりたいことコマンド
通常作業(submodule を触らない)git add -A -- ':!agents/methodology' → git commit
submodule をリモート最新に更新git submodule update --remote agents/methodology
更新を親に記録git add agents/methodology → git commit
submodule のポインタを特定 SHA に固定(submodule 内で checkout 後)git add agents/methodology → git commit

submodule 内(編集したいときだけ)

やりたいことコマンド
編集して commit・pushcd agents/methodology → git add -A → git commit → git push
特定 SHA を取得cd agents/methodology → git fetch origin → git checkout <SHA>

やってはいけない

NG理由
何も考えず git add -A(親で)submodule 内で commit 済みだと、意図しないポインタ更新を巻き込む
submodule 内で commit したのに親で git add を忘れる親のポインタが古いまま。git status に modified content が残り続ける

何が更新されるか

操作ごとに、3つの状態がどう変わるかを整理する。

  • ① remote … GitHub 上の submodule リポジトリ
  • ② 作業ツリー … ローカルにチェックアウトされた実ファイル
  • ③ 親ポインタ … 親リポジトリの commit が記録している SHA
操作① remote② 作業ツリー③ 親ポインタ
submodule 内で git commit変化なし変化なし(既に新)変化なし
submodule 内で git push更新変化なし変化なし
git submodule update --remote変化なし更新変化なし
submodule 内で git checkout <SHA>変化なし更新変化なし
親で git add agents/methodology変化なし変化なし更新(作業ツリーの現在 SHA を記録)
親で git commit変化なし変化なし確定
親で git push変化なし変化なしリモートへ送信

重要: ①〜③は独立して動く。どれか1つを変えても、他は自動では変わらない。

核心:ポインタと実体は別物

親リポジトリが submodule について記録しているのは、特定の SHA が1つだけ。

親 commit A
└── tree: agents/methodology → SHA abc123 ← これが「ポインタ」

親の作業ツリーにある agents/methodology/ の中身(実体)は、そのポインタが指す SHA をチェックアウトしたもの。だから:

  • 実体を新しくしても、ポインタは古いまま(git submodule update や git checkout をしただけでは親の commit は変わらない)
  • ポインタを新しくしても、実体は変わらない(git add agents/methodology は現在の実体を記録するだけ)

この非対称性が submodule の最大の落とし穴。

典型的なワークフロー

シナリオ1:submodule を編集して親に反映

Terminal window
# 1. submodule 内で編集・commit・push
cd agents/methodology
git add -A
git commit -m "feat: ..."
git push origin main
# → SHA が確定(例: 2b266fb)
# 2. 親でポインタを更新して記録
cd ../..
git add agents/methodology
git commit -m "chore(agents): bump methodology to 2b266fb"
git push

「submodule の commit」と「親のポインタ更新」は必ずセット。片方だけだと後で「あれ、反映されてない」になる。

シナリオ2:submodule を他人が更新 → 自分の親に取り込む

Terminal window
# 親のルートで
git submodule update --remote agents/methodology
git add agents/methodology
git commit -m "chore(agents): bump methodology"

cd agents/methodology は不要。--remote が「リモートの最新 main を取ってチェックアウト」までやってくれる。

ただし .gitmodules に branch = main を書いておく必要がある:

[submodule "agents/methodology"]
path = agents/methodology
url = https://github.com/Mitsuki61/agent-methodology.git
branch = main

シナリオ3:通常作業(submodule は触らない)

Terminal window
git add -A -- ':!agents/methodology'
git commit -m "feat: ..."

:!agents/methodology は pathspec の除外指定。これで submodule のポインタを巻き込まずに、他のすべての変更を add できる。

git add -A が危険な理由

状況によって危険度が変わる。

submodule の状態親で git add -A したとき
作業ツリーがクリーン(HEAD が動いていない)ポインタは変わらない。実害なし
作業ツリーが汚れている(未 commit の変更あり)modified content として status に出るが、ポインタは変わらない
submodule 内で commit 済み(HEAD が動いた)ポインタが新 SHA に更新される。意図しないなら事故

判断が面倒なので、常に -- ':!agents/methodology' を付けるのが習慣として安全。これが一番簡単な防御策。

よくある症状と対処

modified: agents/methodology (modified content, untracked content)

意味: 親が記録している SHA と、作業ツリーの実体がズレている。

原因:

  • submodule 内で commit したが、親で git add していない
  • submodule 内に未 commit の変更がある
  • submodule 内に未追跡ファイルがある

対処:

Terminal window
# 意図的に更新したい場合
git add agents/methodology
git commit -m "chore(agents): bump methodology"
# 変更を破棄したい場合
cd agents/methodology
git restore . # 追跡済みを戻す
git clean -fd # 未追跡を消す(消したくないものは先に退避)
cd ../..

git submodule update が「ローカル変更が失われる」と止まる

原因: submodule の作業ツリーに未 commit の変更がある。Git が「上書きしていいか」を確認している。

対処: 変更を commit するか、git restore + git clean で破棄してから再実行。

親の git pull で submodule が動かない

原因: 親の commit には submodule のポインタ更新が含まれているが、git pull だけでは実体はチェックアウトされない。

対処:

Terminal window
git pull
git submodule update --init --recursive

--init は初回の初期化、--recursive はネストした submodule も辿る。

判断に迷ったときの指針

  • submodule の中身を編集する … cd agents/methodology して、そこで普通に Git 操作
  • submodule を更新するだけ … 親のルートで git submodule update --remote
  • 親にポインタ更新を記録する … git add agents/methodology を明示
  • 通常作業 … git add -A -- ':!agents/methodology' で除外

「submodule の実体更新」と「親のポインタ更新」は別操作。これを1つのコマンドで済ませようとすると事故る。常に2段階で考える。

参考

  • git help submodule
  • git help worktree(並列作業したい場合の選択肢)
  • 12-factor app: 設定と秘密情報は環境変数で、リポジトリに置かない