【git】含有子模块的仓库更新

的 Git 子模块更新速查表，按常见场景给出最稳命令👇

克隆（含子模块）

# 一次性把主仓库 + 所有层级子模块都拉齐
git clone --recurse-submodules <repo-url>
# 如果已 clone 但没带子模块：
git submodule update --init --recursive

常规更新（主仓库 + 子模块）

# 方式1：一次完成（推荐）
git pull --recurse-submodules
git submodule update --init --recursive

# 方式2：默认就自动递归（长期设置）
git config submodule.recurse true      # 仅当前仓库
# 或
git config --global submodule.recurse true
# 之后普通 git pull 就会自动递归

子模块“跟踪分支”更新（而不是固定到父仓库记录的提交）

只有当你的子模块在 .gitmodules 里设置了 branch = <name>，或你明确想拉分支最新。

# 把子模块拉到其远端分支的最新（而非父仓记录的commit）
git submodule update --remote --recursive

# 若想把这些更新合并到当前修改（而不是硬切）
git submodule update --remote --recursive --merge
# 或强制切到远端最新（丢本地更改）
git submodule update --remote --recursive --checkout

切换分支后对子模块对齐

git checkout <branch>
# 让子模块检出到父仓该分支记录的精确提交
git submodule update --init --recursive --checkout

子模块 URL/路径变化后同步

# .gitmodules 或远端改了子模块地址
git submodule sync --recursive
git submodule update --init --recursive

查看状态/排错

git submodule status --recursive      # 看当前每个子模块所处提交
git submodule summary --recursive     # 看与父仓记录的差异

提交涉及子模块的改动

子模块本身要在各自仓库提交并推送；父仓只记录“子模块指针（commit hash）”的变化

# 在子模块目录内提交并推送
cd path/to/submodule
git add -A && git commit -m "fix ..." && git push

# 回到父仓，记录指针变化
cd -  # 回父仓根目录
git add path/to/submodule
git commit -m "bump submodule to <new-commit>"
git push

可选：浅克隆加速

git clone --recurse-submodules --depth=1 --shallow-submodules <repo-url>

小结

• 想一把梭更新：git pull --recurse-submodules && git submodule update --init --recursive
• 想长期省心：git config submodule.recurse true
• 想让子模块跟远端分支走：git submodule update --remote --recursive（确认 .gitmodules 里有 branch= 或手动指定分支）