Git标签混乱如何恢复？Python项目ReadTheDocs构建失败求助

1. 浅克隆与有限fetch的限制
   ReadTheDocs先执行了git clone --depth 1的浅克隆，仅拉取仓库最新的一个提交；之后的git fetch命令仅针对master分支拉取最近50个提交，且未明确拉取所有标签。只有当标签指向的提交在这50个提交的历史范围内时，才会被同步到本地。你看到的v.0.12.0.8标签正好在这个范围内，而0.12.0.25对应的提交不在这50个浅历史里，所以RT构建环境中没有这个标签，导致setuptools_scm无法获取正确版本。

2. 标签格式不一致
   仓库中的标签存在两种格式：带v.前缀的v.0.12.0.8和不带前缀的0.12.0.25，setuptools_scm默认的标签识别规则对格式敏感，这种不一致可能引发版本识别混乱。

调整ReadTheDocs的克隆与拉取配置 #

在ReadTheDocs项目的设置中，找到**版本控制（VCS）**相关选项：

• 将克隆深度改为完整克隆（或设置一个足够大的数值，确保覆盖所有标签对应的提交历史）；
• 或在构建前的自定义命令中，添加拉取所有标签的命令：

  git fetch origin --tags
  

  替换原有的fetch命令，或在其之后追加这条命令，确保所有标签都同步到构建环境中。

统一Git标签格式 #

清理或统一仓库中的标签格式，比如全部改为带v前缀（如v0.12.0.25）或全部不带前缀，避免setuptools_scm识别错误。以下是重命名旧标签的示例命令：

# 重命名v.0.12.0.8为v0.12.0.8
git tag v0.12.0.8 v.0.12.0.8
git push origin v0.12.0.8
git tag -d v.0.12.0.8
git push origin :refs/tags/v.0.12.0.8

配置setuptools_scm的标签识别规则 #

在项目的setup.py或pyproject.toml中，明确设置setuptools_scm的标签匹配正则，兼容两种标签格式：

• 若使用setup.py：

  from setuptools import setup
  
  setup(
      use_scm_version={
          "tag_regex": r'^v?(\d+\.\d+\.\d+\.\d+)$',  # 匹配带/不带v前缀的版本标签
          "root": ".",
          "relative_to": __file__
      },
      # 其他配置项...
  )
  

• 若使用pyproject.toml：

  [tool.setuptools_scm]
  tag_regex = "^v?(\\d+\\.\\d+\\.\\d+\\.\\d+)$"
  

这样setuptools_scm就能正确识别不同格式的标签，避免版本读取错误。

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