git submodule 常用命令

核心：主仓库只保存子模块的commit指针，子模块独立仓库；配置存在 .gitmodules

1. 添加子模块

# 基础：添加子模块到指定路径
git submodule add https://xxx/xxx.git modules/xxx

# 指定跟踪分支
git submodule add -b main https://xxx/xxx.git modules/xxx

执行后自动生成 .gitmodules，记得把这个文件 add 提交到主仓库。

2. 克隆带子模块的仓库（最常用）

# 方式1：一次性克隆主仓库+所有子模块（推荐）
git clone --recurse-submodules https://xxx/main.git

# 方式2：先clone主仓库，再初始化拉取子模块
git clone https://xxx/main.git
cd main
# init 注册配置，update 拉取代码；--recursive 支持嵌套子模块
git submodule init
git submodule update
# 合并简写（日常首选）
git submodule update --init --recursive

3. 更新子模块

# ① 按主仓库记录的指针，切到指定commit（默认，detached HEAD）
git submodule update --init --recursive

# ② 拉取子模块远程最新代码（--remote）
git submodule update --remote --recursive
# 只更新某一个子模块
git submodule update --remote modules/xxx

注意：--remote 是拉子模块远程分支最新；更新完主仓库要 git add modules/xxx 提交指针变更，否则别人拉下来看不到新版本

4. 查看状态

git submodule status
# 递归查看嵌套子模块
git submodule status --recursive

符号说明：

• -：未初始化
• +：本地commit 和主仓库记录不一致
• U：冲突

5. 批量操作 foreach（非常好用）

# 在所有子模块里执行命令
git submodule foreach 'git pull'
# 递归所有嵌套子模块
git submodule foreach --recursive 'git status'

6. 同步子模块远程地址 sync

修改了 .gitmodules 里子模块url后，同步到本地config：

git submodule sync --recursive

7. 删除子模块（完整流程）

# 1. 取消注册
git submodule deinit -f modules/xxx
# 2. 删除目录
rm -rf modules/xxx
# 3. 从主仓库git索引、.gitmodules移除
git rm -f modules/xxx
# 提交主仓库变更
git commit -m "remove submodule xxx"

8. 设置子模块默认跟踪分支

git submodule set-branch --branch main modules/xxx

9. 一些高频踩坑补充

• 子模块默认是分离头指针(detached HEAD)，想在子模块正常开发：进入子模块目录 git checkout main
• 主仓库 git pull 不会自动更新子模块，pull完一般要补：git submodule update --init --recursive
• git pull 时自动递归拉子模块：git pull --recurse-submodules

常用一键脚本

# 拉主仓库 + 同步所有子模块
git pull && git submodule update --init --recursive

# 更新所有子模块到远程最新版
git submodule update --remote --recursive
git add .
git commit -m "update all submodules"