用途:在主 Git 仓库中引入其他 Git 仓库,用于外部库、跨项目共享模块、锁定外部依赖到特定版本、管理含独立组件的 monorepo 结构,以及克隆、更新或移除子模块。
主要能力:子模块通过引用特定 commit 锁定版本,路径与 URL 记录在 .gitmodules 文件中,子模块内的改动作为独立 commit 管理。支持添加、克隆、更新、批量操作、移除、状态检查,以及嵌套子模块、修改 URL、浅克隆等进阶操作。
必要用法:添加用 git submodule add <repository-url> <path>,可按分支追踪加 -b main;克隆后初始化用 git submodule update --init --recursive;更新到远程最新用 git submodule update --remote,可加 --merge 或 --rebase;批量执行用 git submodule foreach;移除需依次执行 git submodule deinit <path>、git rm <path>、rm -rf .git/modules/<path> 后提交;状态检查用 git submodule status,输出前缀 - 表示未初始化、+ 表示有本地改动。CI 中需配置递归检出,如 actions/checkout 的 submodules: recursive、GitLab 的 GIT_SUBMODULE_STRATEGY: recursive。
限制与注意:子模块默认处于 detached HEAD 状态,需手动 checkout 分支;克隆后必须初始化;子模块改动后要在主仓库更新引用;私有子模块需配置 SSH 密钥或令牌;.gitmodules 中的相对路径在 fork 时可能出问题;移除时遗漏 .git/modules 缓存会残留;大型仓库可用 --depth 1 浅克隆节省空间。