如何为含Git子模块的项目实现语义化版本控制？

核心原则 #

主项目的语义化版本必须对应确定的代码快照，包括所有子模块的具体提交版本，不能依赖动态的develop分支——否则不同时间拉取的代码状态不一致，无法保证版本的可靠性。

具体操作流程 #

当子模块（如ExternalLibX）更新到新的语义化版本（v1.0.0→v1.1.0）时，按以下步骤操作：

1. 锁定子模块到指定版本
   不要直接拉取develop分支，而是切换到子模块的目标版本（优先用tag，无tag则用具体提交SHA）：

   cd ExternalLibX
   git fetch origin  # 拉取远程最新的tags和提交
   git checkout v1.1.0  # 切换到目标版本的tag
   # 无tag时用具体提交：git checkout <目标提交SHA>
   

2. 提交主项目中子模块的变更
   返回主项目根目录，提交子模块的版本锁定变更：

   cd ..
   git status  # 会看到ExternalLibX显示为modified状态
   git add ExternalLibX
   git commit -m "chore(deps): update ExternalLibX to v1.1.0"
   

   这里的提交信息遵循Conventional Commits规范，方便后续自动识别版本升级类型。

3. 升级主项目的语义化版本
   根据子模块的版本变更类型，决定主项目的版本升级：

   • 子模块补丁更新（v1.0.0→v1.0.1）：主项目升级补丁版本（如v2.3.0→v2.3.1）
   • 子模块小版本更新（v1.0.0→v1.1.0）：主项目升级小版本（如v2.3.0→v2.4.0）
   • 子模块大版本更新（v1.0.0→v2.0.0）：主项目升级大版本（如v2.3.0→v3.0.0）

   手动打tag发布：

   git tag -a v2.4.0 -m "release v2.4.0: update ExternalLibX to v1.1.0"
   git push origin v2.4.0
   

   也可以用semantic-release等自动化工具，根据提交信息自动判断版本并完成发布流程。

4. 关于.gitmodules的配置说明
   无需修改.gitmodules中设置的develop分支——这个配置只是git submodule update --remote命令的默认拉取分支，主项目实际记录的是子模块的具体提交SHA，两者互不冲突。其他开发者克隆主项目时，执行git submodule update会自动拉取到锁定的版本。

实践建议 #

• 要求子模块维护者必须为发布版本打语义化tag（vX.Y.Z），便于快速锁定版本。
• 主项目的提交信息严格遵循Conventional Commits规范，降低版本管理的成本。
• 可编写脚本批量处理多子模块的版本更新，提升效率。

内容的提问来源于stack exchange，提问作者excommunicado