Commitizen执行cz bump生成版本与更新Changelog报错求助

问题根源 #

你的Git标签格式是v.x.y.z（比如v.1.4.3），但pyproject.toml里的tag_format配置是v.$major.$minor.$patch$prerelease，这个配置要求标签格式是vx.y.z（v后面直接跟版本号，没有多余的点）。两者格式不匹配，导致Commitizen无法识别现有标签，触发InvalidVersion报错，进而无法生成增量Changelog。

解决方案步骤 #

1. 修正现有标签格式（核心） #

先清理本地和远程的错误标签，再重新创建符合格式的标签：

• 删除本地错误标签：

  git tag -d v.1.4.3 v.1.4.1 v.1.4.0 v.1.3.2 v.1.3.0 v.0.2.1 v.0.2.0 v.0.1.3 v.0.1.2 v.0.1.0
  

• 如果错误标签已经推送到远程仓库，删除远程标签：

  git push origin :v.1.4.3 :v.1.4.1 :v.1.4.0 :v.1.3.2 :v.1.3.0 :v.0.2.1 :v.0.2.0 :v.0.1.3 :v.0.1.2 :v.0.1.0
  

• 对应原来的提交哈希，重新创建正确格式的标签（把v.改成v）：

  git tag v1.4.3 3512322071378d56adf9a8a5f53
  git tag v1.4.1 e2fffe65272930fefd38aabbad5
  git tag v1.4.0 211b6476cf7928b1ff8206a3305
  git tag v1.3.2 8a26987fca341b0463b83d7181a
  git tag v1.3.0 1e984e45a405501dd37b3cdb11f
  git tag v0.2.1 66e7aa544fd88d3076ee192c872
  git tag v0.2.0 81b36c82d3c624f18b5e202af09
  git tag v0.1.3 d734ac269f4cf287311595bb5e0
  git tag v0.1.2 12856efa7d3d343859d7395e341
  git tag v0.1.0 4ae0d11e08f1baea9aa5c56f865
  

• 推送正确标签到远程：

  git push origin --tags
  

2. 执行正确的版本更新命令 #

用以下命令指定版本号并同步更新Changelog：

cz bump --version 1.4.5 --changelog

（-ch是--changelog的简写，两种写法都有效）

3. 现有Changelog的处理 #

不需要删除现有Changelog。Commitizen会基于修正后的正确标签，自动将新的变更内容追加到现有文件末尾。如果想要重新生成完整的Changelog（覆盖原文件），可以执行：

cz changelog --incremental false

执行前建议备份原Changelog文件，避免数据丢失。

生产环境部署注意事项 #

• 后续版本更新时，Commitizen会自动按照vx.y.z格式生成标签，确保格式统一。
• 推送标签到远程前，检查标签格式是否正确，避免再次出现格式不匹配问题。
• 如果是团队协作，通知其他成员同步清理本地错误标签，拉取远程的正确标签。

内容的提问来源于stack exchange，提问作者André AlcantarA