pypa-hatch/docs/version.md

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:

=== ":octicons-file-code-16: pyproject.toml"

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

=== ":octicons-file-code-16: hatch.toml"

```toml
[version]
path = "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:

=== ":octicons-file-code-16: pyproject.toml"

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

=== ":octicons-file-code-16: hatch.toml"

```toml
[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

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
New: 0.2

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
New: 1rc0

Supported segments

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

Segments	New version
major	2
minor	1.1
micro patch fix	1.0.1
a alpha	1a0
b beta	1b0
c rc pre preview	1rc0
r rev post	1.post0
dev	1.dev0