BumpVer: Automatic Versioning

With the CLI command bumpver, you can search for and update version strings in your project files. It has a flexible pattern syntax to support many version schemes (SemVer, CalVer or otherwise). BumpVer features:

• Configurable version patterns
• Optional Git or Mercurial integration
• Works with plaintext, so you can use it with any project.

Project/Repo:

Code Quality/CI:

• Overview
  • Search and Replace
  • Name Change PyCalVer -> BumpVer
  • Related Projects/Alternatives
• Example Usage
  • Testing a version_pattern
  • Using MAJOR/MINOR/PATCH (SemVer Parts)
  • Auto Increment Parts: BUILD/INC0/INC1
  • Persistent Parts: BUILD/TAG/PYTAG
  • Searching for Patterns with grep
• Reference
  • Command Line
  • Part Overview
  • Normalization Caveats
  • Pattern Examples
  • Week Numbering
• Configuration
  • Configuration Setup
  • Debugging Configuration
• Bump It Up
  • Version State
  • The Current Version
  • Dry Mode
  • VCS Parameters (git/mercurial)

Overview

Search and Replace

With bumpver, you configure a single version_pattern which is then used to

1. Search for version strings in your project files
2. Replace these with an updated/bumped version number.

Your configuration might look something like this:

# 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}"$',
]

Using this configuration, the output of bumpver update --dry might look something like this:

$ 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"

Name Change PyCalVer -> BumpVer

This project was originally developed under the name PyCalVer, with the intent to support various CalVer schemes. The package has since been renamed from PyCalVer to BumpVer and the CLI command from pycalver to bumpver.

This name change is to reduce confusion that this project is only suitable for Python projects or only for CalVer versioning schemes, neither of which is the case.

Related Projects/Alternatives

If you are looking for an alternative, BumpVer was heavily influenced by bumpversion/bump2version. You may also wish to take a look at their list of related projects: bump2version/RELATED.md

Example Usage

You can override the date used by bumpver with the --date= option. Adding this every time would be distracting, so the examples assume the following date:

$ date --iso
2020-10-15

Testing a version_pattern

To test a version_pattern and how to increment it, you can use bumpver test:

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

A version_pattern consists of three kinds of characters:

• Literal text, such as v, ., and -, typically used as delimiters.
• A valid part such as YYYY/WW in the previous example.
• Square brackets [] to mark an optional segment.

The following example uses all three: vYYYY.WW[-TAG]

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

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

Here we see the week number changed from 37 to 41. The test command also shows the normalized version pattern according to PEP440. This removes the "v" prefix and shortens the release tag from -beta to b0.

To remove the release tag, use the option --tag=final.

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

Using MAJOR/MINOR/PATCH (SemVer Parts)

A CalVer version_pattern may not require any flags to determine which part should be incremented, so long as the date has changed. With SemVer you must always specify one of --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

These non date based parts also make sense for a CalVer version_pattern, so that you can create multiple releases in the same month. It is common to include e.g. a PATCH part.

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

Without this flag, we would get an error if the date is still in October.

$ 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

Once the date is in November, the PATCH part will roll over back to zero. This happens whenever parts to the left change (in this case the year and month), just as it does if MAJOR or MINOR were incremented in SemVer.

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

The rollover to zero will happen even if you use the --patch argument, so that your first release in a month will always have a PATCH set to 0 instead of 1. You can make the PATCH part optional with [.PATCH] and always supply the --patch flag in your build script. This will cause the part to be omitted when 0 and added when > 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

With CalVer, the version is based on a calendar date, so you only have to specify such flags if you've already published a release for the current date. Without such a flag, BumpVer will show the error, that the "version did not change".

$ 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]'.

In this case you have to change one of the parts that are not based on a calendar date.

$ 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

If a pattern is not applicable to a version string, then you will get an error message.

$ 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[1-9][0-9]{3})\.(?P1[0-2]|[1-9])'
ERROR   - Invalid version '2020.37' and/or pattern 'YYYY.MM'.

This illustrates that each pattern is internally translated to a regular expression which must match the version string. The --verbose flag will show a verbose form of the regular expression, which may help to debug the discrepancy between the pattern and the version.

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

To fix the above, you can either remove the "v" prefix from the version or add it to the pattern.

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

Auto Increment Parts: INC0/INC1/BUILD

These parts are incremented automatically, and do not use/require a CLI flag: 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

You can make the part optional using the [PART] syntax and it will be added/removed as needed.

$ 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

You can the BUILD part to maintain lexical ordering of version numbers. This means that the expression older < newer will always be true, whether you are dealing with integers or strings, whether you are using software that understands how to parse version numbers or not.

$ 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

Persistent Parts: BUILD/TAG/PYTAG

The BUILD and TAG parts will not rollover/reset. Instead they are carried forward from one version to the next.

$ 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

To remove a release tag, mark it as final with --tag=final.

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

Explicit --set-version

If the various automatic version incrementing methods don't work for you, you can explicitly do --set-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"

Searching for Patterns with grep

You can use bumpver grep to test and debug entries for your configuration.

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

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

When searching your project files for version strings, there are some limitations to keep in mind:

1. A version string cannot span multiple lines.
2. Brackets [] can be escaped with backslash: \[\].
3. There is no way to escape a valid part (so you cannot match the literal text YYYY).

Note that everything in the pattern is treated as literal text, except for a valid part (in all caps).

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

When you write your configuration, you can avoid repeating your version pattern in every search pattern, by using these placeholders

• {version}
• {pep440_version}

Applied to the above example, you can instead write this:

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

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

The corresponding configuration would look like this.

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

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

If you use a version pattern that is not in the PEP440 normalized form (such as the one above), you can nonetheless match version strings in your project files which are in the PEP440 normalized form. To do this, you can use the placeholder {pep440_version} instead of the {version} placeholder.

$ 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,

The placeholder {version} matches 2020.9-beta1, while the placeholder {pep440_version} matches 2020.9b1 (excluding the "v" prefix, the "-" separator and with a short form release tag "b1" instead of "beta1"). These two placeholders make it possible to mostly use your preferred format for version strings, but use a PEP440 compliant/normalized version string where appropriate.

As a neat trick further illustration of how the search and replace works, you might wish to keep the year of your copyright headers up to date.

$ 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:

The corresponding configuration for this pattern would look like this.

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

Note that there must be a match for every entry in file_patterns. If there is no match, bumpver will show an error. This ensures that a pattern is not skipped when your project changes. In this case the side effect is to make sure that every file has a copyright header.

$ 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®ex=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[1-9][0-9]{3})
    [ ]Vandelay[ ]Industries[ ]\-[ ]All[ ]rights[ ]reserved\.
""", flags=re.VERBOSE)
ERROR   - No patterns matched for file 'src/mymodule/utils.py'

Reference

Command Line

$ 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          Set version explicitly.
  --date                 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                 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      Set commit message template.
  --tag-message             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