如何使用setuptools-scm在生成的版本号中添加git分支名称？

问题描述 #

默认情况下，使用git作为版本管理工具时，setuptools_scm生成的版本号格式如下：
mytool-1.2.3.dev42+ba98765.d19700101

我希望在版本号中加入分支名，格式没有固定要求，大致效果如下即可：
mytool-1.2.3.dev42+ba98765.branchname.d19700101

我找到了名为add support for branch name based testing的拉取请求，但它没有相关说明和文档，我不确定它是否能实现我想要的效果。请问我需要在pyproject.toml的[tool.setuptools_scm]配置段中添加什么选项，才能让setuptools_scm生成的版本号包含分支信息？

解决方案 #

你提到的PR已经合并到setuptools_scm主线版本，首先确认你使用的版本≥7.0.0，可通过两种方式实现需求：

方案1：纯配置实现（推荐，无需额外代码）

直接在pyproject.toml的[tool.setuptools_scm]配置段新增对应参数即可：

[tool.setuptools_scm]
# 其余原有配置保持不变，新增以下配置
local_scheme = "node-and-date-and-branch"
# 如果不需要在主干分支显示分支名，可额外添加过滤规则
exclude_branches = ["main", "master"]

生成的版本号会自动在本地版本段插入当前分支名，完全符合你要求的格式。如果测试发现不生效，大概率是版本兼容性问题，直接使用方案2即可。

方案2：自定义格式实现（全版本兼容，灵活调整规则）

如果需要调整分支名的显示位置、过滤规则等，可自定义本地版本生成逻辑：

1. 先在pyproject.toml中指定自定义的local_scheme函数路径：

[tool.setuptools_scm]
# 替换为你项目中实际的函数路径
local_scheme = "your_module.utils.custom_local_version"

2. 在对应路径下编写自定义函数：

from setuptools_scm.git import get_branch
from setuptools_scm.version import get_local_node_and_date

def custom_local_version(version):
    base_local = get_local_node_and_date(version)
    branch = get_branch(version.config)
    # 自定义过滤规则，主干分支不显示分支名
    if not branch or branch in ("main", "master"):
        return base_local
    # 自定义分支名插入位置
    hash_part, date_part = base_local.lstrip("+").split(".", 1)
    return f"+{hash_part}.{branch}.{date_part}"

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