版本控制it 3.1.2

安装与设置

versioningit需要Python 3.8或更高版本。只需使用Python 3的pip安装versioningit及其依赖项即可。

python3 -m pip install versioningit

但是，通常您不需要直接在环境中安装versioningit。相反，您可以在项目的pyproject.toml文件中的build-system.requires键中指定它，如下所示：

# If using Setuptools:
[build-system]
requires = [
    "setuptools",
    "versioningit",
]
build-backend = "setuptools.build_meta"

# If using Hatch:
[build-system]
requires = [
    "hatchling",
    "versioningit",
]
build-backend = "hatchling.build"

# This setting is also required if you're using Hatch:
[tool.hatch.version]
source = "versioningit"

然后，通过在pyproject.toml中添加一个[tool.versioningit]表来配置versioningit。有关详细信息，请参阅文档，但您只需要最少的配置，一个空表即可开始使用。

[tool.versioningit]

versioningit消除了在setup.py、setup.cfg或pyproject.toml（以及使用versioningit时列出的任何显式版本）中列出显式版本的需求，因此您应该删除任何此类设置以减少混淆。

注意：如果您通过pyproject.toml中的[project]表指定项目元数据，则需要将project.dynamic = ["version"]设置为versioningit能够工作。

一旦在pyproject.toml中有了[tool.versioningit]表，并且您的仓库至少有一个标签，使用build或类似工具构建项目时，项目版本将自动根据Git仓库中的最新标签设置。您可以使用versioningit命令（参阅文档）测试您的配置并查看生成的版本。

示例配置

versioningit最大的优点之一是它能够使用占位符字符串配置版本格式。默认格式配置如下所示：

[tool.versioningit.format]
# Format used when there have been commits since the most recent tag:
distance = "{base_version}.post{distance}+{vcs}{rev}"
# Example formatted version: 1.2.3.post42+ge174a1f

# Format used when there are uncommitted changes:
dirty = "{base_version}+d{build_date:%Y%m%d}"
# Example formatted version: 1.2.3+d20230922

# Format used when there are both commits and uncommitted changes:
distance-dirty = "{base_version}.post{distance}+{vcs}{rev}.d{build_date:%Y%m%d}"
# Example formatted version: 1.2.3.post42+ge174a1f.d20230922

其他有趣的格式配置包括

• setuptools_scm使用的默认格式

  [tool.versioningit.next-version]
  method = "smallest"
  
  [tool.versioningit.format]
  distance = "{next_version}.dev{distance}+{vcs}{rev}"
  # Example formatted version: 1.2.4.dev42+ge174a1f
  
  dirty = "{base_version}+d{build_date:%Y%m%d}"
  # Example formatted version: 1.2.3+d20230922
  
  distance-dirty = "{next_version}.dev{distance}+{vcs}{rev}.d{build_date:%Y%m%d}"
  # Example formatted version: 1.2.4.dev42+ge174a1f.d20230922

• versioneer使用的格式

  [tool.versioningit.format]
  distance = "{base_version}+{distance}.{vcs}{rev}"
  # Example formatted version: 1.2.3+42.ge174a1f
  
  dirty = "{base_version}+{distance}.{vcs}{rev}.dirty"
  # Example formatted version: 1.2.3+42.ge174a1f.dirty
  
  distance-dirty = "{base_version}+{distance}.{vcs}{rev}.dirty"
  # Example formatted version: 1.2.3+42.ge174a1f.dirty

• 由vcversioner使用的格式

  [tool.versioningit.format]
  distance = "{base_version}.post{distance}"
  # Example formatted version: 1.2.3.post42
  
  dirty = "{base_version}"
  # Example formatted version: 1.2.3
  
  distance-dirty = "{base_version}.post{distance}"
  # Example formatted version: 1.2.3.post42