git-submodule

Git 子模块管理

补充说明

git submodule 在一个仓库里引用另一个仓库的特定提交。它适合复用公共库或分离部署配置，但克隆、更新和删除都比普通目录复杂。

常用示例

git submodule add https://github.com/example/lib.git vendor/lib
git submodule status
git submodule init
git submodule update
git submodule update --init --recursive
git submodule update --remote
git submodule sync
git submodule foreach 'git pull --ff-only'
git submodule deinit vendor/lib
git submodule set-url vendor/lib https://github.com/example/lib2.git

易错点与排错

• 克隆主仓库不会自动拉子模块；需要 --recurse-submodules 或 submodule update --init。
• 子模块记录的是固定提交，不是分支；--remote 才会跟随远端。
• 子模块默认处于 detached HEAD；直接提交容易丢失，先切分支。
• .gitmodules 要提交；子模块目录本身不存对象，只存 gitlink。
• CI 要显式初始化子模块，否则构建缺文件。
• 删除子模块要同时清理 .gitmodules、索引和 .git/modules，只 rm -rf 不够。
• 私有子模块需要额外认证；SSH agent 和凭据配置要覆盖子模块域名。

相关命令

• git — 版本控制
• git-worktree — 多工作区
• git-lfs — 大文件