Git如何管理子模块_Git submodule使用与配置详解-git-PHP中文网

子模块目录为空是git默认行为，因普通git clone只拉取主仓库、忽略.gitmodules；需用git clone --recurse-submodules或克隆后执行git submodule update --init --recursive才能真正拉取代码。

git如何管理子模块_git submodule使用与配置详解

子模块目录为空不是故障，是 Git 的默认行为；不显式初始化和更新，它永远只是一行配置。

普通 git clone 只拉取主仓库，完全忽略 .gitmodules 文件。子模块目录会被创建，但里面既没有文件、也没有 .git 目录、更没有工作区 —— 它只是个占位符。

正确做法：首次克隆就加 --recurse-submodules 参数，例如 git clone --recurse-submodules https://github.com/user/repo.git
已克隆完？进主目录后运行 git submodule update --init --recursive（--recursive 不能省，否则嵌套子模块仍为空）
CI/CD 中常见失败原因：GitHub Actions 默认不启用递归克隆，需在 actions/checkout@v4 中显式设 submodules: recursive；GitLab CI 则需手动写 git clone --recurse-submodules

git submodule add 只做三件事：写入 .gitmodules、注册路径到索引（模式 160000）、在 .git/modules/ 下建元数据目录。它不执行任何 git clone。

使用四维度框架评估任意 GitLab MR 或 GitHub PR 的复杂度：规模（20%），认知负荷（30%），审查工作量（30%），风险/影响（20%）...

下载

必须补上 git submodule update --init 才会真正克隆并检出子模块内容
目标路径不能预先存在且非空，否则报错 'path/to/submodule' already exists and is not empty；删掉或换路径重试
若子模块 URL 是 SSH（如 git@github.com:user/repo.git），而本地没配 key，update 会卡在 Cloning into 'xxx'... 并提示 Permission denied (publickey)

git submodule update 默认只检出父仓库记录的 commit hash，不会拉新代码。想升级，得用 --remote 模式。

git submodule update --remote --merge：进每个子模块执行 git fetch && git merge origin/main（默认分支是 main 或 master）
若子模块用了非默认分支（如 stable/v2），必须先在 .gitmodules 里加 branch = stable/v2，否则会切错分支或失败
更新后父仓库状态变成 modified: path/to/submodule，这是正常现象 —— 表示子模块 commit hash 已变，需手动 git add path/to/submodule && git commit 才能固化这次升级

直接删目录只会让 git status 一直显示 deleted: path/to/submodule，因为 Git 还在索引和配置里记着它。

必须同步清理三处：rm 掉 .gitmodules 中对应段落、删 .git/config 中 [submodule "xxx"] 区块、执行 git rm --cached path/to/submodule
最后再 rm -rf path/to/submodule 和 git commit
如果子模块本身还有子模块（嵌套），别忘了顺手清掉 .git/modules/path/to/submodule 目录，否则残留元数据可能干扰后续操作