BumpVer: 自动版本化

使用CLI命令 bumpver，您可以在项目文件中搜索和更新版本字符串。它具有灵活的语法模式，支持多种版本方案（SemVer，CalVer 或其他）。BumpVer功能

• 可配置版本模式
• 可选Git或Mercurial集成
• 与纯文本一起工作，因此您可以使用它与任何项目。

项目/仓库

代码质量/CI

• 概述
  • 搜索和替换
  • 名称更改 PyCalVer -> BumpVer
  • 相关项目/替代方案
• 示例用法
  • 测试 version_pattern
  • 使用 MAJOR/MINOR/PATCH（SemVer部分）
  • 自动增加部分： BUILD/INC0/INC1
  • 持久部分： BUILD/TAG/PYTAG
  • 使用 grep 搜索模式
• 参考
  • 命令行
  • 部分概述
  • 规范化注意事项
  • 模式示例
  • 周数编号
• 配置
  • 配置设置
  • 调试配置
• 增加版本号
  • 版本状态
  • 当前版本
  • 干燥模式
  • VCS参数（git/mercurial）

概述

搜索和替换

使用bumpver，你可以配置一个单个的version_pattern，然后将其用于

1. 在项目文件中搜索版本字符串
2. 将这些替换为更新的/增加的版本号。

你的配置可能看起来像这样

# pyproject.toml
[bumpver]
current_version = "1.5.2"
version_pattern = "MAJOR.MINOR.PATCH"

[bumpver.file_patterns]
"setup.py" = [
    'version="{version}",$',
]
"src/mymodule/__init__.py" = [
    '^__version__ = "{version}"$',
]

使用此配置，bumpver update --dry的输出可能看起来像这样

$ bumpver update --patch --dry
INFO    - Old Version: 1.5.2
INFO    - New Version: 1.5.3
--- setup.py
+++ setup.py
@@ -63,7 +63,7 @@
     name="mymodule",
-    version="1.5.2",
+    version="1.5.3",
     description=description,

--- src/mymodule/__init__.py
+++ src/mymodule/__init__.py
@@ -3,3 +3,3 @@

-__version__ = "1.5.2"
+__version__ = "1.5.3"

名称更改 PyCalVer -> BumpVer

该项目最初以PyCalVer的名义开发，旨在支持各种CalVer方案。此后，该包已从PyCalVer重命名为BumpVer，CLI命令从pycalver更改为bumpver。

此名称更改是为了减少这种误解，即此项目仅适用于Python项目或仅适用于CalVer版本号方案，这两种情况都不正确。

相关项目/替代方案

如果您正在寻找替代方案，BumpVer受到了bumpversion/bump2version的很大影响。您还可以查看他们的相关项目列表：bump2version/RELATED.md

示例用法

您可以使用--date=<isodate>选项覆盖bumpver使用的日期。每次都添加它可能会分散注意力，因此示例假设以下日期

$ date --iso
2020-10-15

测试 version_pattern

要测试version_pattern及其增量方式，您可以使用bumpver test

$ bumpver test 'v2020.37' 'vYYYY.WW'
New Version: v2020.41

version_pattern由三种类型的字符组成

• 文字文本，如v、.和-，通常用作分隔符。
• 一个有效的部分，如前一个示例中的YYYY/WW。
• 方括号[]用于标记一个可选段。

以下示例使用所有三种：vYYYY.WW[-TAG]

               vYYYY.WW[-TAG]
literal text   ^    ^   ^

$ bumpver test 'v2020.37-beta' 'vYYYY.WW[-TAG]'
New Version: v2020.41-beta
PEP440     : 2020.41b0

在这里我们看到周数从37变为41。测试命令还显示了根据PEP440规范化的版本模式。这移除了前缀"v"并缩短了发布标签从-beta到b0。

要删除发布标签，请使用选项--tag=final。

$ bumpver test 'v2020.37-beta' 'vYYYY.WW[-TAG]' --tag=final
New Version: v2020.41
PEP440     : 2020.41

使用 MAJOR/MINOR/PATCH（SemVer部分）

CalVer的version_pattern可能不需要任何标志来决定应增加哪个部分，只要日期已更改。使用SemVer时，您必须始终指定--major/--minor/--patch之一。

$ bumpver test '1.2.3' 'MAJOR.MINOR.PATCH[PYTAGNUM]' --major
New Version: 2.0.0

$ bumpver test '1.2.3' 'MAJOR.MINOR.PATCH[PYTAGNUM]' --minor
New Version: 1.3.0

$ bumpver test '1.2.3' 'MAJOR.MINOR.PATCH[PYTAGNUM]' --patch
New Version: 1.2.4

$ bumpver test '1.2.3' 'MAJOR.MINOR.PATCH[PYTAGNUM]' --patch --tag=beta
New Version: 1.2.4b0

$ bumpver test '1.2.4b0' 'MAJOR.MINOR.PATCH[PYTAGNUM]' --tag-num
New Version: 1.2.4b1

这些非日期部分也适用于CalVer的version_pattern，因此您可以在同一个月创建多个版本。通常包括例如PATCH部分。

$ bumpver test '2020.10.0' 'YYYY.MM.PATCH' --patch
New Version: 2020.10.1

如果没有此标志，如果在10月，我们将得到错误。

$ date --iso
2020-10-15

$ bumpver test '2020.10.0' 'YYYY.MM.PATCH'
ERROR   - Invalid arguments or pattern, version did not change.
ERROR   - Version did not change: '2020.10.0'. Invalid version and/or pattern 'YYYY.MM.PATCH'.
INFO    - Perhaps try: bumpver test --patch

一旦日期进入11月，PATCH部分将重置为零。这发生在左侧的部分更改时（在这种情况下是年份和月份），就像在SemVer中增加MAJOR或MINOR时一样。

$ bumpver test '2020.10.1' 'YYYY.MM.PATCH' --date 2020-11-01
New Version: 2020.11.0

重置为零将发生在您使用--patch参数的情况下，这样您在一个月中的第一个版本将始终将PATCH设置为0而不是1。您可以使用[.PATCH]使PATCH部分可选，并在构建脚本中始终提供--patch标志。这将导致当部分为0时省略它，当部分大于0时添加它。

$ bumpver test '2020.9.1' 'YYYY.MM[.PATCH]' --patch
New Version: 2020.10

$ bumpver test '2020.10' 'YYYY.MM[.PATCH]' --patch
New Version: 2020.10.1

$ bumpver test '2020.10.1' 'YYYY.MM[.PATCH]' --patch
New Version: 2020.10.2

在CalVer中，版本基于日历日期，因此您只有在已为当前日期发布了一个版本时才需要指定此类标志。没有此类标志，BumpVer将显示“版本未更改”的错误。

$ bumpver test 'v2020.41-beta0' 'vYYYY.WW[-TAGNUM]'
ERROR   - Invalid arguments or pattern, version did not change.
ERROR   - Invalid version 'v2020.41-beta0' and/or pattern 'vYYYY.WW[-TAGNUM]'.

在这种情况下，您必须更改一个不是基于日历日期的部分。

$ bumpver test 'v2020.41-beta0' 'vYYYY.WW[-TAGNUM]' --tag-num
New Version: v2020.41-beta1
PEP440     : 2020.41b1

$ bumpver test 'v2020.41-beta0' 'vYYYY.WW[-TAGNUM]' --tag=final
New Version: v2020.41
PEP440     : 2020.41

如果模式不适用于版本字符串，则将得到错误消息。

$ bumpver test '2020.37' 'YYYY.MM'     # expected to fail because 37 is not valid for part MM
ERROR   - Incomplete match '2020.3' for version string '2020.37' with pattern 'YYYY.MM'/'(?P<year_y>[1-9][0-9]{3})\.(?P<month>1[0-2]|[1-9])'
ERROR   - Invalid version '2020.37' and/or pattern 'YYYY.MM'.

这说明了每个模式都内部转换为正则表达式，必须匹配版本字符串。--verbose 标志将显示详细的正则表达式，这可能有助于调试模式和版本之间的差异。

$ bumpver test 'v2020.37' 'YYYY.WW' --verbose  # missing "v" prefix
INFO    - Using pattern YYYY.WW
INFO    - regex = re.compile(r"""
    (?P<year_y>[1-9][0-9]{3})
    \.
    (?P<week_w>5[0-2]|[1-4][0-9]|[0-9])
""", flags=re.VERBOSE)
ERROR   - Invalid version string 'v2020.37' for pattern ...

为了修复上述问题，您可以选择从版本中移除 "v" 前缀或将它添加到模式中。

$ bumpver test 'v2020.37' 'vYYYY.WW'   # added "v" prefix
New Version: v2020.41
PEP440     : 2020.41

自动递增部分：INC0/INC1/BUILD

这些部分会自动递增，并且不需要使用 CLI 标志：BUILD/INC0/INC1。

$ bumpver test '2020.10.1' 'YYYY.MM.INC0'
New Version: 2020.10.2

$ bumpver test '2020.10.2' 'YYYY.MM.INC0' --date 2020-11-01
New Version: 2020.11.0

您可以使用 [PART] 语法使部分可选，并根据需要添加或删除。

$ bumpver test '2020.10' 'YYYY.MM[.INC0]'
New Version: 2020.10.1

$ bumpver test '2020.10.1' 'YYYY.MM[.INC0]' --date 2020-11-01
New Version: 2020.11

您可以将 BUILD 部分用于 维护版本号的词法排序。这意味着无论您是处理整数还是字符串，无论您是否使用理解如何解析版本号的软件，表达式 older < newer 总是成立。

$ bumpver test '2020.1001' 'YYYY.BUILD'
New Version: 2020.1002

$ bumpver test '2020.1002' 'YYYY.BUILD'
New Version: 2020.1003

$ bumpver test '2020.1999' 'YYYY.BUILD'
New Version: 2020.22000

持久部分： BUILD/TAG/PYTAG

BUILD 和 TAG 部分不会回滚/重置。相反，它们会从版本带到下一个版本。

$ bumpver test 'v2020.1051-beta' 'vYYYY.BUILD[-TAG]'
New Version: v2020.1052-beta
PEP440     : 2020.1052b0

$ bumpver test 'v2020.1051-beta' 'vYYYY.BUILD[-TAG]' --date 2021-01-01
New Version: v2021.1052-beta
PEP440     : 2021.1052b0

$ bumpver test 'v2020.1051-beta' 'vYYYY.BUILD[-TAG]' --tag=rc
New Version: v2020.1052-rc
PEP440     : 2020.1052rc0

要删除发布标签，使用 --tag=final 标记它为最终版本。

$ bumpver test 'v2020.1051-beta' 'vYYYY.BUILD[-TAG]' --tag=final
New Version: v2020.1052
PEP440     : 2020.1052

显式 --set-version

如果各种自动版本递增方法对您不起作用，您可以显式执行 --set-version=<version>。

$ bumpver update --dry --set-version="v2020.1060"
INFO    - Old Version: v2020.1051-beta
INFO    - New Version: v2020.1060
--- setup.py
+++ setup.py
@@ -63,7 +63,7 @@
     name="mymodule",
-    version="2020.1051b0",
+    version="2020.1060",
     description=description,

--- src/mymodule/__init__.py
+++ src/mymodule/__init__.py
@@ -3,3 +3,3 @@

-__version__ = "v2020.1051-beta"
+__version__ = "v2020.1060"

使用 grep 搜索模式

您可以使用 bumpver grep 测试和调试配置条目。

$ bumpver grep \
	'__version__ = "YYYY.MM[-TAGNUM]"' \
	src/module/__init__.py

 3:
 4: __version__ = "2020.9-beta1"
 5:

在搜索项目文件中的版本字符串时，需要注意一些限制

1. 版本字符串不能跨多行。
2. 括号 [] 可以用反斜杠转义：\[\]。
3. 无法转义有效部分（因此您不能匹配文本 YYYY 的字面值）。

请注意，模式中的所有内容都被视为字面文本，除非是有效部分（全部大写）。

              __version__ = "YYYY.MM[-TAGNUM]"
literal text  ^^^^^^^^^^^^^^^    ^   ^       ^

在编写您的配置时，您可以通过使用这些占位符来避免在每个搜索模式中重复版本模式

• {version}
• {pep440_version}

应用于上述示例，您可以改写为

$ bumpver grep \
  --version-pattern "YYYY.MM[-TAGNUM]"  \
  '__version__ = "{version}"' \
  src/module/__init__.py

 3:
 4: __version__ = "2020.9-beta1"
 5:

相应的配置将如下所示。

[bumpver]
current_version = "2020.9-beta1"
version_pattern = "YYYY.MM[-TAGNUM]"
...

[bumpver:file_patterns]
src/module/__init__.py
  __version__ = "{version}"
...

如果您使用的是非 PEP440 规范化形式的版本模式（如上述示例），您仍然可以匹配项目中 是 PEP440 规范化形式的版本字符串。为此，您可以使用占位符 {pep440_version} 而不是 {version} 占位符。

$ bumpver grep --version-pattern "YYYY.MM[-TAGNUM]" 'version="{pep440_version}"' setup.py
setup.py
  65:     url="https://github.com/org/project",
  66:     version="2020.9b1",
  67:     description=description,

占位符 {version} 匹配 2020.9-beta1，而占位符 {pep440_version} 匹配 2020.9b1（排除 "v" 前缀、"-" 分隔符，并使用短形式发布标签 "b1" 而不是 "beta1"）。这两个占位符使您能够主要使用您首选的版本字符串格式，但在适当的地方使用 PEP440 兼容/规范化的版本字符串。

作为一个 小窍门，进一步说明搜索和替换的工作方式，您可能希望保持版权头中的年份是最新的。

$ bumpver grep 'Copyright (c) 2018-YYYY' src/mymodule/*.py | head
src/mymodule/__init__.py
   3:
   4: # Copyright (c) 2018-2020 Vandelay Industries - All rights reserved.
   5:

src/mymodule/config.py
   3:
   4: # Copyright (c) 2018-2020 Vandelay Industries - All rights reserved.
   5:

此模式的相应配置如下所示。

[bumpver:file_patterns]
...
src/mymodule/*.py
  Copyright (c) 2018-YYYY Vandelay Industries - All rights reserved.

请注意，必须对 file_patterns 中的每个条目进行匹配。如果没有匹配项，bumpver 将显示错误。这确保了当您的项目发生变化时，不会跳过一个模式。在这种情况下，副作用是确保每个文件都有一个版权头。

$ bumpver update --dry
ERROR   - No match for pattern 'Copyright (c) 2018-YYYY Vandelay Industries - All rights reserved.'
ERROR   -
# https://regex101.com/?flavor=python&flags=gmx&regex=Copyright%5B%20%5D%5C%28c%5C%29%0A%5B%20%5D2018%5C-%0A%28%3FP%3Cyear_y%3E%5B1-9%5D%5B0-9%5D%7B3%7D%29%0A%5B%20%5DVandelay%5B%20%5DIndustries%5B%20%5D%5C-%5B%20%5DAll%5B%20%5Drights%5B%20%5Dreserved%5C.
regex = re.compile(r"""
    Copyright[ ]\(c\)
    [ ]2018\-
    (?P<year_y>[1-9][0-9]{3})
    [ ]Vandelay[ ]Industries[ ]\-[ ]All[ ]rights[ ]reserved\.
""", flags=re.VERBOSE)
ERROR   - No patterns matched for file 'src/mymodule/utils.py'

参考

命令行

$ bumpver --help
Usage: bumpver [OPTIONS] COMMAND [ARGS]...

  Automatically update version strings in plaintext files.

Options:
  --version      Show the version and exit.
  -v, --verbose  Control log level. -vv for debug level.
  -h, --help     Show this message and exit.

Commands:
  grep    Search file(s) for a version pattern.
  init    Initialize [bumpver] configuration.
  show    Show current version of your project.
  test    Increment a version number for demo purposes.
  update  Update project files with the incremented version string.

$ bumpver update --help
Usage: bumpver update [OPTIONS]

  Update project files with the incremented version string.

Options:
  -d, --dry                       Display diff of changes, don't rewrite
                                  files.
  -f, --fetch / -n, --no-fetch    Sync tags from remote origin.
  -v, --verbose                   Control log level. -vv for debug level.
  --allow-dirty                   Commit even when working directory is has
                                  uncomitted changes. (WARNING: The commit
                                  will still be aborted if there are
                                  uncomitted to files with version strings.
  --ignore-vcs-tag                Ignore VCS tag invariant and update version
                                  anyway.
  --set-version <VERSION>         Set version explicitly.
  --date <ISODATE>                Set explicit date in format YYYY-0M-0D (e.g.
                                  2023-07-10).
  --pin-date                      Leave date components unchanged.
  --pin-increments                Leave the auto-increments INC0 and INC1
                                  unchanged.
  --tag-num                       Increment release tag number (rc1, rc2,
                                  rc3..).
  -t, --tag <NAME>                Override release tag of current_version.
                                  Valid options are: alpha, beta, dev, rc,
                                  post, final.
  -p, --patch                     Increment PATCH component.
  -m, --minor                     Increment MINOR component.
  --major                         Increment MAJOR component.
  -c, --commit-message <TMPL>     Set commit message template.
  --tag-message <TMPL>            Set tag message template.
  --commit / --no-commit          Create a commit with all updated files.
  --tag-commit / --no-tag-commit  Tag the newly created commit.
  --push / --no-push              Push to the default remote.
  --tag-scope [default|global|branch]
                                  Tag scope for the current version.
  --pre-commit-hook <PATH>        Custom script that runs before the commit
                                  step
  --post-commit-hook <PATH>       Custom script that runs after the commit
                                  step is completed
  -h, --help                      Show this message and exit.

为了帮助 shell 脚本自动化，您可以使用 bumpver show --environ。

$ bumpver show -n --environ
YEAR_Y=2020
YEAR_G=
...
TAG=final
...

$ eval $(bumpver show -n --environ)
$ echo $TAG
final

部分概述

尽可能的情况下，这些模式匹配来自 CalVer.org 的约定。

以下内容也可用，但在决定使用之前，请先查看规范化注意事项。

• ¹ 周一为一周的第一天。
• ² 周日为一周的第一天。
• ³ ISO 8601周。第1周包含1月4日。

规范化注意事项

包管理器和安装工具将解析您的版本号。在解析时，您的版本号可能经过规范化处理，并且可能不与您指定的完全相同。在Python的情况下，打包工具（如pip、twine、setuptools）遵循PEP440规范化规则。

根据这些规则（以及其他规则）

• 任何非数字前缀（如v）将被移除
• 分隔部分的leading zeros将被截断 XX.08 -> XX.8
• 标签被转换为简短形式（-alpha -> a0）

例如

• 模式：vYY.0M.0D[-TAG]
• 版本：v20.08.02-beta
• PEP440：20.8.2b0

我不知道有任何技术原因需要在您的整个项目中使用规范化表示。然而，如果您选择始终以规范化形式存在的模式，它将有助于避免混淆。例如，可能不明显，v20.08.02-beta与20.8.2b0是相同的。

对您选择的version_pattern的进一步考虑是，它可能由不将其解释为版本号但将其仅视为任何其他字符串的工具进行处理。如果它们按字母顺序排序的工具（例如，来自git tags）列出的版本号没有按发布顺序排列，这可能会让您的用户感到困惑

$ git tag
18.6b4
18.9b0
19.10b0
19.3b0
20.8b0
20.8b1

如果您希望避免这种情况，您应该使用保持字典顺序的模式。

模式示例

• ¹ 如果 PATCH > 9
• ² 对于2100年，部分YY将产生0

周数编号

周编号有点特殊，因为它取决于你对“周”的定义

• 一周的第一天是星期一或星期天。
• 范围是0-52或1-53。
• 在年初或年末，你可能会有部分周或跨越多个年份的一周。

如果你使用VV/0V，请注意你不能同时使用YYYY。相反，使用GGGG。这是为了避免一个边缘情况，即如果你的版本号是在新年左右创建的，它可能会倒退。

                   YYYY WW UU  GGGG VV
2020-12-26 (Sat):  2020 51 51  2020 52
2020-12-27 (Sun):  2020 51 52  2020 52
2020-12-28 (Mon):  2020 52 52  2020 53
2020-12-29 (Tue):  2020 52 52  2020 53
2020-12-30 (Wed):  2020 52 52  2020 53
2020-12-31 (Thu):  2020 52 52  2020 53
2021-01-01 (Fri):  2021 00 00  2020 53
2021-01-02 (Sat):  2021 00 00  2020 53
2021-01-03 (Sun):  2021 00 01  2020 53
2021-01-04 (Mon):  2021 01 01  2021 01

配置

配置设置

使用bumpver init为项目创建初始配置。

$ pip install bumpver
...
Installing collected packages: click toml lexid bumpver
Successfully installed bumpver-2023.1129

$ cd myproject
~/myproject/

$ bumpver init --dry
Exiting because of '-d/--dry'. Would have written to bumpver.toml:

    [bumpver]
    current_version = "2020.1001a0"
    version_pattern = "YYYY.BUILD[PYTAGNUM]"
    commit_message = "bump version to {new_version}"
    tag_message = "{new_version}"
    tag_scope = "default"
    pre_commit_hook = ""
    post_commit_hook = ""
    commit = true
    tag = true
    push = true

    [bumpver.file_patterns]
    "README.md" = [
        "{version}",
        "{pep440_version}",
    ]
    "bumpver.toml" = [
        'current_version = "{version}"',
    ]

如果你已经在你的项目中有了配置文件（例如setup.cfg或pyproject.toml），那么bumpver init将更新该文件。

~/myproject
$ bumpver init
Updated pyproject.toml

你的pyproject.toml现在可能看起来像这样

[bumpver]
current_version = "2019.1001-alpha"
version_pattern = "YYYY.BUILD[-TAG]"
commit_message = "bump version to {new_version}"
tag_message = "{new_version}"
tag_scope = "default"
pre_commit_hook = ""
post_commit_hook = ""
commit = true
tag = true
push = true

[bumpver.file_patterns]
"pyproject.toml" = [
    'current_version = "{version}"',
]
"setup.py" = [
    'version="{pep440_version}",',
]
"README.md" = [
    '{version}',
    '{pep440_version}',
]

调试配置

对于[bumpver:file_patterns]中的条目，你可能会遇到两种失败模式

• 假阴性：一个模式不会匹配它应该匹配的相关文件中的版本号。
• 假阳性：一个模式会匹配它不应该匹配的内容（不太可能）。

你第一次尝试使用bumpver update时最明显会看到这样的案例。

$ bumpver update --dry --no-fetch
INFO    - Old Version: 2020.1001-alpha
INFO    - New Version: 2020.1002-alpha
ERROR   - No match for pattern 'version="YYYY.BUILD[PYTAGNUM]",'
ERROR   -
# https://regex101.com/?flavor=python&flags=gmx&regex=version%3D%5C%22%0A%28%3FP%3Cyear_y%3E%5B1-9%5D%5B0-9%5D%7B3%7D%29%0A%5C.%0A%28%3FP%3Cbid%3E%5B1-9%5D%5B0-9%5D%2A%29%0A%28%3F%3A%0A%20%20%20%20%28%3FP%3Cpytag%3Epost%7Crc%7Ca%7Cb%29%0A%20%20%20%20%28%3FP%3Cnum%3E%5B0-9%5D%2B%29%0A%29%3F%0A%5C%22%2C
regex = re.compile(r"""
    version=\"
    (?P<year_y>[1-9][0-9]{3})
    \.
    (?P<bid>[1-9][0-9]*)
    (?:
        (?P<pytag>post|rc|a|b)
        (?P<num>[0-9]+)
    )?
    \",
""", flags=re.VERBOSE)
ERROR   - No patterns matched for file 'setup.py'

还显示了内部使用的正则表达式，你可以使用它来调试问题，例如在regex101.com上。

要调试此类问题，你可以简化你的模式，并使用bumpver grep来查看是否可以找到匹配项。

$ bumpver grep 'YYYY.BUILD[PYTAGNUM]' setup.py
 45:    name='myproject',
 46:    version='2019.1001b0',
 47:    license='MIT',

在这里，我们可以看到setup.py的模式应该更改为使用单引号而不是双引号。

与bumpver update一样，如果你的模式未找到，bumpver grep将显示一个包含它使用的正则表达式的错误消息，以帮助你调试问题。

$ bumpver grep 'YYYY.BUILD[PYTAGNUM]' setup.py
ERROR   - Pattern not found: 'YYYY.BUILD[PYTAGNUM]'
# https://regex101.com/...

一个更复杂的模式的例子是，你想要保持README中的版本徽章是最新的。

$ bumpver grep 'shields.io/badge/CalVer-YYYY.BUILD[--TAG]-blue' README.md
  61:
  62: [img_version]: https://img.shields.io/badge/CalVer-2020.1001--beta-blue
  63: [url_version]: https://pypi.ac.cn/org/package/

增加版本号

版本状态

current_version被视为全局状态，必须存储在某处。通常，这可能是VERSION文件，或作为仓库一部分的其他文件。这带来了风险，即并行分支可能会有不同的状态。如果current_version仅由本地签出中的文件定义，那么对于不同的提交，不同的系统可能会生成相同的版本。

为了避免这个问题，bumpver将Git/Mercurial标签视为第二个数据源，根据tag_scope选项，为最新版本尝试以最原子的方式更改此状态。这就是为什么一些bumpver命令的操作可能需要几秒钟，因为它正在与远程仓库同步以获取最新版本，并尽快推送任何新版本标签。

当前版本

当前版本取决于配置的tag_scope，并且是

• 在创建任何标签之前，bumpver将始终默认为bumpver.toml / setup.cfg / pyproject.toml中current_version的值。
• 只有匹配配置中version_pattern的Git/Mercurial标签才会被考虑，并使用pkg_resources.parse_version进行排序。

作为执行bumpver update和bumpver show的一部分，你的本地标签将使用git fetch --tags / hg pull进行更新。

$ bumpver show -vv
2020-10-18T20:20:58.062 DEBUG   bumpver.cli       - Logging configured.
2020-10-18T20:20:58.065 DEBUG   bumpver.config    - Config Parsed: Config(
    ...
2020-10-18T20:20:58.067 DEBUG   bumpver.vcs       - vcs found: git
2020-10-18T20:20:58.067 INFO    bumpver.vcs       - fetching tags from remote (to turn off use: -n / --no-fetch)
2020-10-18T20:20:58.068 DEBUG   bumpver.vcs       - git fetch
2020-10-18T20:21:00.886 DEBUG   bumpver.vcs       - git tag --list
2020-10-18T20:21:00.890 INFO    bumpver.cli       - Latest version from git tag: 2020.1019
Current Version: 2020.1019

在这里，我们可以看到

• Git的版本比我们本地的版本新（2020.1019与2020.1018）。
• 从远程仓库获取标签花费了2秒钟。

在版本号升级之前获取标签的方法，有助于降低最新标签本地未知的风险。这意味着同一版本不太可能由不同系统针对不同的提交生成。这可能会导致版本标签模糊不清，虽然这并非世界末日，但最好还是避免。通常情况下，这可能会发生在你有一个在相同时间触发多个构建的构建系统时。

对于一个小型项目（只有一个维护者且没有自动化打包），这不是一个问题，你可以始终使用-n/--no-fetch来跳过获取标签。

干燥模式

一旦你有了有效的配置，你可以使用bumpver update --dry来查看它会做出的更改（并且不修改你的项目文件）。

$ bumpver update --dry --no-fetch
INFO    - Old Version: 2019.1001-beta
INFO    - New Version: 2019.1002-beta
--- README.md
+++ README.md
@@ -11,7 +11,7 @@

 [![Supported Python Versions][pyversions_img]][pyversions_ref]
-[![Version 2019.1001-beta][version_img]][version_ref]
+[![Version 2019.1002-beta][version_img]][version_ref]
 [![PyPI Releases][pypi_img]][pypi_ref]

--- src/mymodule_v1/__init__.py
+++ src/mymodule_v1/__init__.py
@@ -1,1 +1,1 @@
-__version__ = "2019.1001-beta"
+__version__ = "2019.1002-beta"

--- src/mymodule_v2/__init__.py
+++ src/mymodule_v2/__init__.py
@@ -1,1 +1,1 @@
-__version__ = "2019.1001-beta"
+__version__ = "2019.1002-beta"

--- setup.py
+++ setup.py
@@ -44,7 +44,7 @@
     name="myproject",
-    version="2019.1001b0",
+    version="2019.1002b0",
     license="MIT",

VCS参数（git/mercurial）

bumpver update执行的单独步骤

1. 获取来自源代码控制系统的标签。
2. 获取最新版本。
3. 生成更新的版本字符串。
4. 检查你是否没有未提交的本地更改。
5. 在配置中的所有文件中替换版本字符串file_patterns。
6. 运行预提交钩子。
7. 提交更新后的文件。
8. 运行提交后钩子。
9. 打标签新的提交。
10. 推送新的提交和标签。

可以使用以下参数配置这些步骤

• ¹ 可用的模板占位符：{new_version}、{old_version}、{new_version_pep440}、{old_version_pep440}
• ² 需要commit = True

一个示例配置可能如下所示

[bumpver]
...
commit_message = "bump version to {new_version}"
tag_message = "{new_version}"
tag_scope = "default"
pre_commit_hook = "scripts/run_checks.sh"
post_commit_hook = "scripts/update_changelog.sh"
commit = True
tag = True
push = True

如果一切看起来都正常，你可以执行bumpver update。

$ bumpver update --verbose
INFO    - fetching tags from remote (to turn off use: -n / --no-fetch)
INFO    - Old Version: 2020.1005
INFO    - New Version: 2020.1006
INFO    - Run pre-commit hook: scripts/run_checks.sh
INFO    - 	...
INFO    - git commit --message 'bump version to 2020.1006'
INFO    - Run post-commit hook: scripts/update_changelog.sh
INFO    - 	...
INFO    - git tag --annotate 2020.1006 --message 2020.1006
INFO    - git push origin --follow-tags 2020.1006 HEAD

你还可以通过将这些命令行标志传递给bumpver update来覆盖配置值

自定义提交信息

除了commit_message配置之外，你还可以通过使用-c/--commit-message=<TMPL>参数来覆盖用作提交信息的字符串。

$ bumpver update --tag final --commit-message 'bump version {old_version} -> {new_version} [ci-publish]' --verbose
INFO    - Old Version: 2021.1005b0
INFO    - New Version: 2021.1006
INFO    - git commit --message 'bump version 2020.1005b0 -> 2021.1006 [ci-publish]'
INFO    - git tag --annotate 2020.1006 --message '2020.1006'
INFO    - git push origin --follow-tags 2020.1006 HEAD

由于这是一个手动操作（而不是长期配置选项），你可以使用占位符OLD和NEW来代替更冗长的{old_version}和{new_version}。

$ bumpver update -f -t final -c '[final-version] OLD -> NEW'
...
INFO    - Old Version: 1.2.0b2
INFO    - New Version: 1.2.0
INFO    - git commit --message '[final-version] 1.2.0b2 -> 1.2.0'
...

自定义标签信息

与--commit-message类似，你可以通过使用--tag-message=<TMPL>参数或tag_message配置来提供标签信息模板。

$ bumpver update -f -t final --tag-message 'release NEW'
INFO    - Old Version: 1.2.0b2
INFO    - New Version: 1.2.0
...
INFO    - git tag --annotate 1.2.0 --message 'release 1.2.0'
...

你可以使用与--commit-message模板相同的占位符。

如果提供了空白的标签信息，bumpver将使用Git的轻量级标签。否则，它将使用注解Git标签。有关Git标签的更多信息，请参阅这里。

$ bumpver update -f -t final --tag-message ''
INFO    - Old Version: 1.2.0b2
INFO    - New Version: 1.2.0
...
INFO    - git tag 1.2.0
...

提交前/后钩子

Bumpver允许你在提交步骤之前和之后运行自定义脚本，分别使用--pre-commit-hook=<PATH>和--post-commit-hook=<PATH>参数，或者它们的配置对应项pre_commit_hook和post_commit_hook。这两个选项都需要设置commit=True，且<PATH>必须是相对于工作目录的绝对路径或相对路径。

如果脚本失败（以 return_code!=0 退出）bumpver 将会中止，后续的所有步骤都不会执行，例如 提交、打标签 和 推送。

为了方便使用，提供了两个环境变量可以在脚本中使用： BUMPVER_OLD_VERSION 和 BUMPVER_NEW_VERSION。

示例

#!/usr/bin/env python
# File path: scripts/print_new_version.py
from os import environ
print("The new version is " + environ.get('BUMPVER_NEW_VERSION', ''))

$ bumpver update --post-commit-hook scripts/print_new_version.py
INFO    - fetching tags from remote (to turn off use: -n / --no-fetch)
INFO    - Old Version: 2023.1001-alpha
INFO    - New Version: 2023.1002-alpha
INFO    - git commit --message 'bump version 2023.1001-alpha -> 2023.1002-alpha'
INFO    - Run post-commit hook: scripts/print_new_version.py
INFO    - 	The new version is 2023.1002-alpha
INFO    - git tag --annotate 2023.1002-alpha --message '2023.1002-alpha'
INFO    - git push origin --follow-tags 2023.1002-alpha HEAD

确保您的脚本可执行，否则您可能会遇到

$ bumpver update --post-commit-hook scripts/print_new_version.py
...
INFO    - Run post-commit hook: scripts/print_new_version.py
ERROR   - 	[Errno 13] Permission denied: 'scripts/print_new_version.py'
ERROR   - Script exited with an error. Stopping

贡献者

关于 https://github.com/mbarkhau/bumpver 的变更日志

BumpVer 2023.1129

• 修复 #224：添加 --environ 以发出 0 值。废弃 -e/--env。
• 添加 #223：添加对 .bumpver.toml 的支持

感谢 Adrianne 提供此问题报告。感谢 Xavier Francisco 的贡献。

BumpVer 2023.1127

• 添加 #222：添加部分 HEXHASH。

感谢 Atwam 的贡献。

BumpVer 2023.1126

• 添加 #214：支持预/后提交钩子。
• 添加 #219：修复 Windows 上的 pathlib 问题。
• 修复 #201：SemVer 特殊情况更好的错误信息。
• 更新 #215：贪婪模式匹配更好的错误信息。
• 更新 #216：在 REAMDE 示例中使用 .toml 格式。

感谢 Sven Lohrmann 的贡献。感谢 Maikel Punie 的问题报告。感谢您在调试 Windows 问题上的帮助

• Søren Furbo
• Michal Vašut
• Justin Cooksey
• yqbear

BumpVer 2023.1125

• 添加 #188：添加 --tag-scope=<SCOPE> 以支持分支的独立版本控制。
• 添加 #185：添加 --tag-message=<TMPL> 参数和 tag_message 配置选项。
• 修复 #209：使 --no-tag-commit 与 --follow-tags 一起使用。

感谢 Sven Lohrmann 的贡献。感谢 tardis4500 的问题报告。

BumpVer 2023.1124

• 修复 #208：修复处理带有 PEP440 时钟的版本。

感谢 Wen Kokke 的问题报告。

BumpVer 2023.1122

• 修复 #207：添加 --ignore-vcs-tag 以支持升级旧版本

感谢 Jusong Yu 的贡献。

BumpVer 2023.1121

• 修复 #200：修复与打包 23.0 的兼容性。
• 修复 #203：将 dev 添加到有效的发布标签列表中

感谢 Sharon Yogev 的贡献。

BumpVer 2022.1120

• 修复 #196：添加 --pin-increments。

感谢 Markus Holtermann 的贡献。

BumpVer 2022.1119

• 修复 #190：允许在同一行上使用多个模式

• 修复 #182：为vcs命令使用引号

BumpVer 2022.1118

• 修复 #181：启用使用 ^$ 字符限制匹配行首和行尾
• 将 GITHASH 添加到 version_pattern (@mpasternak)

BumpVer 2022.1116

• 修复：当从vcs标签更新时，版本比较不正确。

  在将更新的版本与最新的vcs标签进行比较时，使用了不充分的字符串比较，而不是比较解析后的版本。

感谢 Timo Ludwig @timoludwig 的贡献。

BumpVer 2022.1115

• 修复：使用默认日期值。

  在解析当前版本时，如果没有指定任何日期部分（例如，SemVer的情况），则使用当前日期填充默认部分。

  这允许更新版权头中的YYYY模式，即使对于不使用CalVer模式的工程项目也是如此。

  感谢 Benjamin Depardon (@bdepardo) 发现并报告此问题。

BumpVer 2021.1114

• 添加：为 bumpver update 添加覆盖vcs选项的标志

感谢 Timo Ludwig @timoludwig 的贡献。

BumpVer 2021.1113

• 添加：为 bumpver update 添加 --commit-message 参数

BumpVer 2021.1112

• 修复：在Windows上从源代码构建。

BumpVer 2021.1110

• 修复 github#157：改进错误信息。
• 修复 github#158：阐明 PYTAGNUM "部分"。

感谢 Julien Palard @JulienPalard 进行测试和反馈。

BumpVer 2021.1109

• 添加 -e/--env 选项以支持shell脚本自动化。
• 修复 github#151：当设置 TAG=final 时，TAGNUM 的无效增量。

感谢 Dave Wapstra @dwapstra 的贡献。

BumpVer 2020.1108

• 不匹配空模式（如果大括号 [] 未转义，可能会导致整个文件被重写）。

BumpVer 2020.1107

• 非Beta版本（没有重大代码更改）。

BumpVer 2020.1105-beta

• 修复 gitlab#15：修复配置解析的角落情况。
• 修复 gitlab#16：修复标签/Pytag的回滚处理。

BumpVer 2020.1104-beta

• 修复 gitlab#13：添加 --set-version=<VERSION> 以显式设置版本。
• 修复 gitlab#14：使用 pyproject.toml 作为 PEP 518 的要求解析 tool.bumpver。

BumpVer 2020.1100-beta

将包和模块从 PyCalVer 重命名为 BumpVer。这种名称更改是由于该项目是Python特定的，或者只适用于CalVer版本控制方案，这两种情况都不成立。

此版本包括新的模式语法。

version_pattern = "vYYYY0M.BUILD[-RELEASE]"             # new style
version_pattern = "v{year}{month}{build}{release}"      # old style

version_pattern = "MAJOR.MINOR.PATCH"                   # new style semver
version_pattern = "{MAJOR}.{MINOR}.{PATCH}"             # old style semver

此切换的主要原因有：

• 启用使用大括号 [PART] 的可选部分。
• 使语法与CalVer.org上使用的约定一致。

将保留旧语法，但所有文档都已更新，主要引用新样式模式。

• 将主要仓库从gitlab切换到github。
• 新 gitlab#7：新样式模式语法。
  • 更好地支持周数。
  • 更好地支持可选部分。
  • 新：现在 BUILD 部分从 1000 开始而不是 0001，以避免截断前导零。
  • 新增：添加 INC0（基于0）和 INC1（基于1）部分，实现自动增量和回滚。
  • 新增：当日期部分的值向左变化时，MAJOR/MINOR/PATCH/INC 将进行回滚。
• 新增 gitlab#2：添加 grep 子命令以帮助调试模式。
• 新增 gitlab#10：添加 --pin-date 选项以保持日期部分不变，仅增加非日期部分。
• 新增：添加 --date=<iso-date> 参数以设置显式日期（而不是当前日期）。
• 新增：添加 --release-num 选项以增加 alphaN/betaN/a0/b0 等版本号。
• 新增：添加更好的错误消息以调试正则表达式。
• 新增 gitlab#9：使提交信息可配置。
• 修复 gitlab#12：在排序非词法版本标签（例如SemVer）时出现错误。
• 修复 gitlab#11：当使用 --verbose 时显示正则表达式。
• 修复 gitlab#8：现在 bumpver update 也将推送 HEAD（之前只推送标签本身）。
• 修复：不允许使用 --release=dev。与其它发布标签相比，dev 发布的语义不同，需要进一步开发以正确支持它们。
• 修复：如果存在多个相同文件的条目，则忽略 file_patterns 中的条目。

本版本不再包含 pycalver.lexid 模块，该模块已移动到自己的包：[pypi.org/project/lexid/](https://pypi.ac.cn/project/lexid/).

感谢本版本的所有贡献者：@LucidOne, @khanguslee, @chaudum

PyCalVer v202010.1042

• 在 README.md 中添加弃用警告

PyCalVer v201907.0036

• 修复：如果配置了 commit=False，则不使用 git/hg 命令（感谢 @valentin87）

PyCalVer v201907.0035

• 修复 gitlab#6：添加部分 {month_short}、{dom_short}、{doy_short}。
• 修复 gitlab#5：在使用带有 SemVer 的 bump 时提供更好的警告（需要 --major/--minor/--patch 之一）
• 修复 gitlab#4：使 {release} 部分可选，以便解析由 --release=final 生成的版本。

PyCalVer v201903.0030

• 修复：使用配置中的模式而不是硬编码的 {pycalver} 模式。
• 修复：改进对 git/hg 问题的错误消息。
• 新增：为配置文件添加隐式默认模式。

PyCalVer v201903.0028

• 修复：当配置的文件不在版本控制之下时添加警告。
• 新增：bump --dry 的彩色输出

PyCalVer v201902.0027

• 修复：允许使用 --release=post
• 修复：改进对坏模式的错误报告
• 修复：与 "?" 相关的正则表达式转义问题

PyCalVer v201902.0024

• 新增：支持文件模式中的通配符。
• 修复：改进对无效配置的错误报告。

PyCalVer v201902.0020

• 新增：支持更多的自定义版本模式。

PyCalVer v201812.0018

• 修复：改进对带有 "-final" 发布的模式的替换处理。

PyCalVer v201812.0017

• 修复 [github#2]：pycalver init 出错。
• 修复模式转义问题。
• 为 cli 添加更多测试。
• 整理文档。

PyCalVer v201812.0011-beta

• 使用 git/hg 添加版本标签。
• 使用 git/hg 标签作为最新版本的 SSOT。
• 开始使用 [https://gitlab.com/mbarkhau/bootstrapit](https://gitlab.com/mbarkhau/bootstrapit)
• 迁移到 [https://gitlab.com/mbarkhau/pycalver](https://gitlab.com/mbarkhau/pycalver)

PyCalVer v201809.0001-alpha

• 初始版本