bump2version

注意

这是对优秀的bumpversion项目的维护分支。

概述

使用单条命令提高您的软件版本号！

这是一个小巧的命令行工具，通过正确递增您的源代码中的所有版本字符串来简化软件发布。同时创建提交和标签。

• 版本格式高度可配置
• 无需任何版本控制系统，但如果可用，则乐于从Git和Mercurial读取标签信息，并将提交和标签写入其中
• 仅处理文本文件，因此它不针对任何特定的编程语言
• 支持Python 3和PyPy3

如果您想使用Python 2，请使用pip>=9，您将获得最后一个支持版本，或者固定bump2version<1。

替代方案

如果bump2version不完全满足您的需求，您可以考虑其他执行类似或相关任务的工具： ALTERNATIVES.md。

安装

您可以通过以下方式从Python包索引（PyPI）下载和安装此软件的最新版本

pip install --upgrade bump2version

注意：pip install bumpversion现在安装的是最新的bump2version！

变更日志

请在此处找到变更日志：CHANGELOG.md

用法

注意：在此文档中，您可以使用 bumpversion 或 bump2version 互换使用。

有两种操作模式：在命令行上进行单文件操作，以及使用配置文件（bumpversion.cfg）进行更复杂的多文件操作。

bump2version [options] part [file]

部分

必需

要增加的版本部分，例如 minor。

有效值包括在 --serialize / --parse 选项中给出的值。

示例：将 0.5.1 升级到 0.6.0

 bump2version --current-version 0.5.1 minor src/VERSION

文件

[可选]
默认：无

将要修改的文件。

此文件将添加到配置文件中指定的文件列表中，该列表在 [bumpversion:file:…] 部分。如果您只想重写命令行上指定的文件，请使用 --no-configured-files。

示例：将 1.1.9 升级到 2.0.0

 bump2version --current-version 1.1.9 major setup.py

配置文件

所有选项都可以在名为 .bumpversion.cfg 的配置文件中指定，这样一旦您知道 bump2version 需要如何配置某个特定软件包，您就可以稍后不指定选项而运行它。您应该将此文件添加到 VCS，以便其他人也可以升级版本。

命令行上的选项优先于配置文件中的选项，配置文件中的选项优先于从环境变量和默认值派生出的选项。

示例 .bumpversion.cfg

[bumpversion]
current_version = 0.2.9
commit = True
tag = True

[bumpversion:file:setup.py]

如果没有 .bumpversion.cfg，bump2version 还会查找 setup.cfg 以进行配置。

配置文件 -- 全局配置

通用配置分组在 [bumpversion] 部分。

current_version

必需
默认：无

升级前的软件包当前版本。

也作为 --current-version 使用（例如，bump2version --current-version 0.5.1 patch setup.py）。

new_version

[可选]
默认：无

增加后的软件包版本。如果未提供，将自动确定。

也作为 --new-version 使用（例如，要从 0.5.1 直接跳到 0.6.1，请使用：bump2version --current-version 0.5.1 --new-version 0.6.1 patch setup.py）。

tag = (True | False)

[可选]
默认：False（不创建标签）

是否创建标签，即带有前缀字符 "v" 的新版本。如果您使用 git，请不要忘记使用带 --tags 标志的 git-push。

也作为命令行上的 (--tag | --no-tag) 使用。

sign_tags = (True | False)

[可选]
默认：False（不签名标签）

是否签名标签。

也作为命令行上的 (--sign-tags | --no-sign-tags) 使用。

tag_name =

[可选]
默认： v{new_version}

要创建的标签的名称。仅在使用 --tag / tag = True 时有效。

这使用 Python 格式字符串语法 进行模板化。在模板上下文中可用的是 current_version 和 new_version，以及 current_[part] 和 new_[part]（例如 'current_major' 或 'new_patch'）。此外，所有环境变量都公开，以 $ 为前缀。您还可以使用变量 now 或 utcnow 来获取当前时间戳。两者都接受 datetime 格式化（例如在 {now:%d.%m.%Y} 中使用时）。

也作为命令行标志 tag-name 使用。示例用法：bump2version --tag-name 'release-{new_version}' patch

此外，您还可以通过使用 --tag-message TAG_MESSAGE 提供标签消息。示例用法：bump2version --tag-name 'release-{new_version}' --tag-message "Release {new_version}" patch

• 如果没有提供标签消息或标记标签，bumpversion 在 Git 中使用一个 轻量级 标签。否则，它使用一个 注解 Git 标签。您可以在这里了解更多关于 Git 标签的信息。

commit = (True | False)

[可选]
默认值： False（不创建提交）

是否使用 Git 或 Mercurial 创建提交。

也作为 (--commit | --no-commit) 使用。

在许多项目中，在提交之前运行一个预提交钩子是很常见的，如果失败则中止提交。对于某些用例，可能希望在增加版本并且 commit = True 时，预提交钩子应执行与常规提交略有不同的操作。例如，仅对软件的实际发布运行一组扩展的检查。为了允许预提交钩子区分 bumpversion 提交，在执行提交命令时设置了 BUMPVERSION_CURRENT_VERSION 和 BUMPVERSION_NEW_VERSION 环境变量。

message =

[可选]
默认值： 增加版本：{current_version} → {new_version}

创建提交时使用的提交信息。仅当使用 --commit / commit = True 时有效。

这使用 Python 格式字符串语法 进行模板化。在模板上下文中可用的是 current_version 和 new_version，以及 current_[part] 和 new_[part]（例如 'current_major' 或 'new_patch'）。此外，所有环境变量都公开，以 $ 为前缀。您还可以使用变量 now 或 utcnow 来获取当前时间戳。两者都接受 datetime 格式化（例如在 {now:%d.%m.%Y} 中使用时）。

也作为命令行标志 --message 使用。示例用法：bump2version --message '[{now:%Y-%m-%d}] Jenkins 构建 {$BUILD_NUMBER}: {new_version}' patch）

commit_args =

[可选
默认值： empty

传递给提交命令的额外参数。仅当使用 --commit / commit = True 时有效。

例如，这可以用来添加 -s 生成提交信息中的 Signed-off-by: 行。

可以在单独的行上指定多个参数。

也作为命令行标志 --commit-args 使用，在这种情况下只能指定一个参数。

配置文件 -- 部分特定配置

版本字符串由一个或多个部分组成，例如版本 1.0.2 有三个部分，由点（.）字符分隔。在默认配置中，这些部分的名称为 major、minor、patch，但是您可以使用 parse/serialize 选项进行自定义。

默认情况下，所有部分都视为数字，即它们的初始值是 0，并且它们作为整数递增。此外，如果它对于序列化不是必需的，则值 0 被视为可选的，即它在 --serialize 可能性中的表示不是必需的。例如，版本 1.4.0 等于 1.4，如果 {major}.{minor} 作为 serialize 值给出。

对于高级版本控制方案，可能需要非数字部分（例如，为了标识 alpha 或 beta 版本 以指示开发阶段、软件包的风味或发布名称）。要这样做，可以使用包含部分名称的 [bumpversion:part:…] 部分（例如，在名为 [bumpversion:part:release_name] 的部分中配置名为 release_name 的部分）。

以下选项在部分配置内有效

values =

默认值： numeric（即 0、1、2、…）

所有将在增加特定部分时迭代的值的显式列表。

示例

[bumpversion:part:release_name]
values =
  witty-warthog
  ridiculous-rat
  marvelous-mantis

optional_value =

默认值： values = 的第一个条目。

如果该部分的值匹配此值，则认为它是可选的，即它在 --serialize 可能性中的表示不是必需的。

示例

[bumpversion]
current_version = 1.alpha
parse = (?P<num>\d+)(\.(?P<release>.*))?
serialize =
  {num}.{release}
  {num}

[bumpversion:part:release]
optional_value = gamma
values =
  alpha
  beta
  gamma

在这里，bump2version release 会将 1.alpha 增加到 1.beta。再次执行 bump2version release 会将 1.beta 增加到 1，因为配置为可选的 release 是 gamma。

first_value =

默认值： values = 的第一个条目。

当部分被重置时，值将被设置为此处指定的值。

配置文件 -- 文件特定配置

此配置位于以下部分：[bumpversion:file:…] 或 [bumpversion:glob:…]

两者，file: 和 glob: 的配置相同。它们的区别在于，文件会直接匹配文件名，例如 requirements.txt。而 glob 会通过通配符匹配多个文件，例如 **/pom.xml。

注意：配置文件格式要求每个部分的标题必须是唯一的。如果您想多次处理某个文件，可以在 file 关键字之间添加一个描述，例如：[bumpversion:file (特殊一个):…]。

parse =

默认值： (?P\d+)\.(?P\d+)\.(?P\d+)

正则表达式（使用 Python 正则表达式语法）说明如何查找和解析版本字符串。

必须解析由 serialize = 产生的所有字符串。命名匹配组（"(?P...)"）提供了作为 part 参数的值。

也作为 --parse 提供

serialize =

默认值： {major}.{minor}.{patch}

指定如何将版本部分序列化为版本字符串的模板。

这使用 Python 格式化字符串语法 进行模板化。在模板上下文中，有在 parse = 中指定的命名组的解析值以及所有环境变量（以 $ 开头）。

可以指定多次，bumpversion 将尝试序列化格式，从第一个开始，并选择最后一个所有值都可以这样表示的格式

serialize =
  {major}.{minor}
  {major}

给定上面的示例，新版本 1.9 将被序列化为 1.9，但版本 2.0 将被序列化为 2。

也作为 --serialize 提供。命令行上的多个值给定，如 --serialize {major}.{minor} --serialize {major}

search =

默认值： {current_version}

模板字符串，用于在文件中搜索要替换的字符串。如果当前版本号可能在文件中出现多次，并且只想更改其中一次，则很有用。可以是多行，使用 Python 格式化字符串语法 进行模板化

replace =

默认值： {new_version}

创建字符串的模板，用于替换文件中的当前版本号。

给定此 requirements.txt

Django>=1.5.6,<1.6
MyProject==1.5.6

使用此 .bumpversion.cfg 将确保仅更改包含 MyProject 的行

[bumpversion]
current_version = 1.5.6

[bumpversion:file:requirements.txt]
search = MyProject=={current_version}
replace = MyProject=={new_version}

可以是多行，使用 Python 格式化字符串语法 进行模板化

命令行选项

上述大多数配置值也可以作为命令行选项提供。此外，还提供以下选项

--dry-run, -n 不更改任何文件，只是假装。最好与 --verbose 一起使用。

--allow-dirty 通常，如果工作目录已更改，bumpversion 将会中止以保护您免于发布未标记版本的文件和/或覆盖未保存的更改。使用此选项可以覆盖此检查。

--no-configured-files 不会更新/检查 bumpversion.cfg 中指定的文件。与 dry-run 类似，但还会避免检查文件。当您只想更新一个文件时也很有用，例如 bump2version --no-configured-files major my-file.txt

--verbose 将有用信息打印到 stderr

--list 将机器可读信息列出到 stdout，供其他程序消费。

示例输出

current_version=0.0.18
new_version=0.0.19

-h, --help 打印帮助并退出

在脚本中使用 bumpversion

如果您需要在脚本中使用bumpversion生成的版本，可以使用--list选项，并结合grep和sed。

例如，如果您使用git-flow管理项目并希望自动创建发布版本，在运行git flow release start之前，您需要知道新的版本号。

在bash脚本中获取它的标准方式是

bump2version --dry-run --list <part> | grep <field name> | sed -r s,"^.*=",,

其中part是指您正在更新的版本号的组成部分。您需要指定--dry-run以避免bumpversion实际更新版本号。

例如，如果您正在更新次要版本并寻找新版本号，则变为

bump2version --dry-run --list minor | grep new_version | sed -r s,"^.*=",,

使用bumpversion维护Go项目中的go.mod文件

在模块感知的Go项目中，当您创建大于v1的模块主版本时，您的模块名称需要包含主版本号（例如github.com/myorg/myproject/v2）。

您可以使用bump2version通过使用parse和serialize选项来维护go.mod文件中的主版本号，如下所示

• 示例.bumpversion.cfg文件

    [bumpversion]
    current_version = 2.0.0
    commit = True

    [bumpversion:file:go.mod]
    parse = (?P<major>\d+)
    serialize = {major}
    search = module github.com/myorg/myproject/v{current_version}
    replace = module github.com/myorg/myproject/v{new_version}

• 示例go.mod文件

    module github.com/myorg/myproject/v2

    go 1.12

    require (
        ...
    )

然后运行此命令以创建项目的3.0.0版本

    bump2version --new-version 3.0.0 major

您的go.mod文件现在包含以下模块指令

    module github.com/myorg/myproject/v3

开发 & 贡献

感谢贡献者！您可以在以下位置找到完整的列表：https://github.com/c4urself/bump2version/graphs/contributors

请参阅我们的CONTRIBUTING.md

此项目在GitHub上开发，包括测试、文档的补丁非常欢迎，以及错误报告！如果此工具不支持您开发工作流程中所有关于提升版本的功能，请打开一个问题，因为它旨在非常灵活。

许可证

bump2version采用MIT许可证 - 请参阅LICENSE.rst文件以获取详细信息