颠簸2版本

笔记

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

概述

使用单个命令对您的软件进行版本升级！

一个小型命令行工具，通过以正确的增量更新源代码中的所有版本字符串来简化发布软件。还创建提交和标签：

• 版本格式是高度可配置的
• 无需任何 VCS 即可工作，但很高兴从 Git 和 Mercurial 中读取标签信息并将提交和标签写入（如果可用）
• 只处理文本文件，因此它不特定于任何编程语言
• 支持 Python 3 和 PyPy3

如果您想使用 Python 2，请使用pip>=9，您将获得最新支持的版本，或 pin 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]

part

必需的

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

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

将 0.5.1 增加到 0.6.0 的示例：

 bump2version --current-version 0.5.1 minor src/VERSION

file

[可选]
默认值：无

将被修改的文件。

该文件被添加到[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（例如to go from 0.5.1 directly to 0.6.1：）bump2version --current-version 0.5.1 --new-version 0.6.1 patch setup.py。

tag = (True | False)

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

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

也可以在命令行上作为(--tag | --no-tag).

sign_tags = (True | False)

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

是否签署标签。

也可以在命令行上作为(--sign-tags | --no-sign-tags).

tag_name =

[可选]
默认： v{new_version}

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

这是使用Python Format String Syntax模板化的。在模板上下文中可用的是current_versionandnew_version 以及current_[part]and new_[part]（例如 ' current_major' 或 ' new_patch'）。此外，所有环境变量都被公开，前缀为$. 您还可以使用变量now或utcnow获取当前时间戳。两者都接受日期时间格式（当像在中一样使用时{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使用lightweightGit 中的标记。否则，它会使用annotatedGit 标签。您可以在此处阅读有关 Git 标记的更多信息。

commit = (True | False)

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

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

也可作为(--commit | --no-commit).

在许多项目中，通常会在提交之前运行一个预提交挂钩，并且在失败的情况下会中止提交。对于某些用例，可能希望在更新版本和拥有commit = True时，预提交钩子应该执行与常规提交略有不同的操作。例如，仅为软件的实际版本运行一组扩展的检查。为了让 pre-commit 钩子区分一个碰撞版本提交，在执行 commit 命令时设置BUMPVERSION_CURRENT_VERSION和BUMPVERSION_NEW_VERSION 环境变量。

message =

[可选]
默认： Bump version: {current_version} → {new_version}

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

这是使用Python Format String Syntax模板化的。在模板上下文中可用的是current_versionandnew_version 以及current_[part]and new_[part]（例如 ' current_major' 或 ' new_patch'）。此外，所有环境变量都被公开，前缀为$. 您还可以使用变量now或utcnow获取当前时间戳。两者都接受日期时间格式（当像在中一样使用时{now:%d.%m.%Y}）。

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

commit_args =

[可选
默认值：空

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

例如，这对于添加-s到提交消息中的生成Signed-off-by:行很有用。

可以在不同的行上指定多个参数。

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

配置文件——特定于部分的配置

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

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

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

以下选项在部件配置中有效：

values =

默认值：数字（即，，，，0... ）12

碰撞该特定部分时将迭代的所有值的显式列表。

例子：

[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.alpha1.betabump2version release1.beta1releasegamma

first_value =

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

当部件复位时，该值将设置为此处指定的值。

配置文件——文件特定的配置

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

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

注意：配置文件格式要求每个节头是唯一的。如果您想多次处理某个文件，您可以在file关键字的括号之间附加一个描述： [bumpversion:file (special one):…].

parse =

默认： (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)

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

需要解析由serialize =. 命名匹配组 (" (?P<name>...)") 提供值 to 作为part参数。

也可作为--parse

serialize =

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

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

这是使用Python Format String Syntax模板化的。在模板上下文中可用的是在中指定的命名组的解析值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 中指定的文件。类似于空运行，但也会避免检查文件。当您只想更新一个文件时也很有用，例如， bump2version --no-configured-files major my-file.txt

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

--list 将机器可读信息列出到标准输出以供其他程序使用。

示例输出：

current_version=0.0.18
new_version=0.0.19

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

在脚本中使用碰撞版本

如果您需要在脚本中使用由 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以避免碰撞版本实际碰撞版本号。

例如，如果您正在更新次要编号并寻找新的版本号，这将变为

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

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

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

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

• 示例.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文件了解详细信息