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・push | cd 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 を編集して親に反映
# 1. submodule 内で編集・commit・pushcd agents/methodologygit add -Agit commit -m "feat: ..."git push origin main# → SHA が確定(例: 2b266fb)
# 2. 親でポインタを更新して記録cd ../..git add agents/methodologygit commit -m "chore(agents): bump methodology to 2b266fb"git push「submodule の commit」と「親のポインタ更新」は必ずセット。片方だけだと後で「あれ、反映されてない」になる。
シナリオ2:submodule を他人が更新 → 自分の親に取り込む
# 親のルートでgit submodule update --remote agents/methodologygit add agents/methodologygit 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 は触らない)
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 内に未追跡ファイルがある
対処:
# 意図的に更新したい場合git add agents/methodologygit commit -m "chore(agents): bump methodology"
# 変更を破棄したい場合cd agents/methodologygit restore . # 追跡済みを戻すgit clean -fd # 未追跡を消す(消したくないものは先に退避)cd ../..git submodule update が「ローカル変更が失われる」と止まる
原因: submodule の作業ツリーに未 commit の変更がある。Git が「上書きしていいか」を確認している。
対処: 変更を commit するか、git restore + git clean で破棄してから再実行。
親の git pull で submodule が動かない
原因: 親の commit には submodule のポインタ更新が含まれているが、git pull だけでは実体はチェックアウトされない。
対処:
git pullgit 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 submodulegit help worktree(並列作業したい場合の選択肢)- 12-factor app: 設定と秘密情報は環境変数で、リポジトリに置かない