【Git】submoduleの更新が反映されない原因と解決策｜9パターン診断・自動化設定・総合リカバリ完全ガイド

# 親で pull したのに submoduleが古いまま
$ git pull
$ cat submodule/VERSION
1.2.0    # ← 期待は 2.0.0

$ git status
  modified:   submodule (new commits)
# これが「submoduleのポインタが進んでいるが取り込まれていない」合図

# 親リポジトリが記録しているのは「特定のコミットSHA」
git ls-files --stage | grep "^160000"
# 例: 160000 a1b2c3d4e5f6... 0  submodule/
# 160000 がsubmodule（ファイルモード扱い）
# SHA部分が「親が指すsubmoduleのコミット」

# .gitmodulesには設定（URL/pathなど）
cat .gitmodules
# [submodule "submodule-name"]
#     path = submodule-name
#     url = https://github.com/org/sub.git
#     branch = main  （あれば）

git submodule status
# 出力例:
#    a1b2c3d4e5f6 submodule/sub1 (v1.2.0)          ← 正常（ポインタ＝作業ツリー）
# + e4f5g6a7b8c9 submodule/sub2 (heads/feature)   ← 作業ツリーがポインタと異なる
# - 1a2b3c4d5e6f submodule/sub3                   ← まだ初期化されていない
# U 7j8k9l0m1n2o submodule/sub4                   ← conflict未解決

# 記号の意味:
#   （なし） 正常
#   -       未初期化（submodule update --init が必要）
#   +       ポインタと作業ツリーが不一致（submodule updateで合わせる）
#   U       merge conflict

# 再帰付きで全submodule確認
git submodule status --recursive

# よりリッチな情報
git submodule summary

# submodule内に降りての状態確認
cd path/to/submodule
git status
git log --oneline -5

# clone時に一発で
git clone --recurse-submodules <repo-url>
# 短縮形
git clone --recursive <repo-url>

# clone済みなら別途
git submodule update --init --recursive

# 特定のsubmoduleだけ初期化
git submodule update --init -- path/to/submodule

# 親をpull
git pull

# submoduleのポインタを作業ツリーに適用
git submodule update --recursive

# これで親が指すSHAにsubmoduleの作業ツリーが揃う

# 確認
git submodule status
# 記号が出ていなければOK

# submodule.recurseを有効化
git config --global submodule.recurse true

# これでpull/checkout/resetなどでsubmoduleも自動更新される
git pull   # 自動で submodule update --recursive 相当が走る

# submodule内に入る
cd path/to/submodule

# detachedから開発ブランチへ
git switch main
git pull --ff-only
# または既存ブランチ
git switch feature/xxx
# 作業してcommit
git add .
git commit -m "feat: 機能追加"
git push

# 親に戻ってポインタ更新をcommit
cd ../..
git add path/to/submodule
git commit -m "Update submodule to latest main"
git push

# .gitmodulesでブランチ指定
# [submodule "path/to/submodule"]
#     path = path/to/submodule
#     url = git@github.com:org/sub.git
#     branch = main

# リモートブランチの先端に追従
git submodule update --remote --recursive

# --merge オプションでmerge戦略
git submodule update --remote --merge --recursive
# --rebase オプションでrebase戦略
git submodule update --remote --rebase --recursive

# 親にポインタ更新をcommit
git add path/to/submodule
git commit -m "Bump submodule to latest main"
git push

# .gitmodulesでURL変更後
git submodule sync --recursive
# → .git/config にも新URLが反映される

# 設定後に再取得
git submodule update --init --recursive

# URLをSSHからHTTPSに切り替える例
git config -f .gitmodules submodule.path/to/sub.url \
  https://github.com/org/sub.git
git submodule sync --recursive
git submodule update --init --recursive

# submodule内で確認
cd path/to/submodule
git status

# 退避（untrackedも含める）
git stash push -u -m "wip in submodule"

# 親に戻って更新
cd ../..
git submodule update --recursive

# 必要ならstash復元
cd path/to/submodule
git stash pop

# 変更を完全に破棄して更新
git submodule update --recursive --force

# URLをSSHに揃える
git config -f .gitmodules submodule.path/to/sub.url \
  git@github.com:org/sub.git
git submodule sync --recursive

# HTTPSでトークン認証
git config -f .gitmodules submodule.path/to/sub.url \
  https://TOKEN@github.com/org/sub.git

# insteadOf で無理やり書き換え（CI環境で便利）
git config --global url."git@github.com:".insteadOf "https://github.com/"

# SSH接続テスト
ssh -T git@github.com

# --recursive が常に必要
git submodule update --init --recursive
git submodule update --recursive
git submodule sync --recursive
git submodule status --recursive

# 自動で再帰になるよう設定
git config --global submodule.recurse true

# submoduleに降りて履歴を完全化
cd path/to/submodule
git fetch --unshallow
# あるいは
git fetch --depth=2147483647

# 親が指すSHAにcheckout
cd ../..
git submodule update --recursive

# CI環境なら最初から深くcloneする
# GitHub Actions: checkout@v4 の fetch-depth: 0

# submoduleのポインタが変わっていることを確認
git status
#   modified:   path/to/submodule (new commits)

# ポインタ変更をadd
git add path/to/submodule

# 何のために更新したかを明記してcommit
git commit -m "chore: submodule path/to/submodule を v1.3.0 に更新"

# push
git push

# submoduleコマンドを自動再帰に
git config --global submodule.recurse true

# clone時に自動recurse
git config --global clone.recurseSubmodules true

# 参照掃除
git config --global fetch.prune true

# fetch時にsubmoduleも取得
git config --global fetch.recurseSubmodules on-demand

# statusでsubmoduleの要約表示
git config --global status.submoduleSummary true

# diffにsubmoduleの変更内容を表示
git config --global diff.submodule log

# 親で退避ブランチ
git switch -c safety/submodule-$(date +%Y%m%d-%H%M)

# 参照同期
git fetch --prune
git submodule sync --recursive

# 強制再取得（ローカル変更は破棄されるので注意）
git submodule update --init --recursive --force

# それでもダメなら submodule を一度消して再初期化
# .gitmodulesの該当submoduleだけ削除
# git submodule deinit -f path/to/submodule
# rm -rf .git/modules/path/to/submodule
# git rm -f path/to/submodule
# その後、.gitmodulesに再追加して submodule update --init

git submodule update --init --recursive

git submodule update --recursive
# 今後自動化したいなら
git config --global submodule.recurse true

# .gitmodulesにbranch=main を追加
git submodule update --remote --recursive
# 親にcommit
git add path/to/submodule
git commit -m "chore: submodule追従更新"
git push

# .gitmodulesでURL変更
git submodule sync --recursive
git submodule update --init --recursive