Versioning¶

Configuration¶

When the version is not statically set, configuration is defined in the tool.hatch.version table. The source option determines the source to use for retrieving and updating the version. The regex source is used by default.

The regex source requires an option path that represents a relative path to a file containing the project's version:

[tool.hatch.version]
path = "src/hatch_demo/__about__.py"

[version]
path = "src/hatch_demo/__about__.py"

The default pattern looks for a variable named __version__ or VERSION that is set to a string containing the version, optionally prefixed with the lowercase letter v.

If this doesn't reflect how you store the version, you can define a different regular expression using the pattern option:

[tool.hatch.version]
path = "pkg/__init__.py"
pattern = "BUILD = 'b(?P<version>)'"

[version]
path = "pkg/__init__.py"
pattern = "BUILD = 'b(?P<version>)'"

The pattern must have a named group called version that represents the version.

Display¶

Invoking the version command without any arguments will display the current version of the project:

$ hatch version
0.0.1

Updating¶

You can update the version like so:

$ hatch version "0.1.0"
Old: 0.0.1
New: 0.1.0

The scheme option determines the scheme to use for parsing both the existing and new versions. The standard scheme is used by default, which is based on PEP 440.

Rather than setting the version explicitly, you can select the name of a segment used to increment the version:

$ hatch version minor
Old: 0.1.0
New: 0.2.0

You can chain multiple segment updates with a comma. For example, if you wanted to release a preview of your project's first major version, you could do:

$ hatch version major,rc
Old: 0.2.0
New: 1.0.0rc0

When you want to release the final version, you would do:

$ hatch version release
Old: 1.0.0rc0
New: 1.0.0

Supported segments¶

Here are the supported segments and how they would influence an existing version of 1.0.0: