Commit-based semantic versioning - highly configurable and tag-free.
✨ Features 🚀 Quick start 📚 Documentation 🤝 Contribute 👍 Adopters 📜 Legal
comver is a tool for calculating semantic versioning of your project using only commit messages - no tags required!
- Separation of concerns: versioning focuses on technical aspects, not marketing. You can now use tags solely for communication.
- Highly configurable: include only relevant commits by filtering via
message,author,email, or even commit path. - Immutable: version is calculated directly from the commit history. Tags can now be used more meaningfully (e.g., to mark a major milestone or release).
- Batteries-included: integrate with pdm, Hatch or uv.
- Verifiable: verify that a specific version was generated from a given commit chain - more resistant to tampering like dependency substitution attacks
Semantic versioning based on Git tags has a few limitations:
- Teams may avoid bumping the
majorversion due to the perceived weight of the change. Double versioning scheme; one version for technical changes, another for public releases is a viable mitigation. - Tag creation by
bots (e.g. during automated releases) lead to problems withbranch protection(see here). - Not all commits are relevant for release versions
(e.g., CI changes, bot updates, or tooling config),
yet many schemes count them in. With filtering,
comvercan exclude such noise. - Tags are mutable by default and can be re-pointed. By calculating the version
based on commits, and combining it with the commit
shaand a configchecksum, you get verifiable and reproducible results.
Note
You can jump straight into the action and check comver
tutorials.
> pip install comverImportant
Although written in Python, comver can be used with any programming language.
If your commits follow the Conventional Commits format, run:
> comver calculateThis will output a version string in the MAJOR.MINOR.PATCH format:
23.1.3 # OutputConfiguration can be done either in pyproject.toml
(recommended for Python-first project) or in a separate
.comver.toml file (recommended for non-python projects):
| pyproject.toml | .comver.toml |
|---|---|
[tool.comver]
# Only commits to these paths are considered
path_includes = [
"src/*",
"pyproject.toml",
]
# Commits done by GitHub Actions bot are discarded
author_name_excludes = [
"github-actions[bot]",
] |
# No [tool.comver] needed here
# Source only commits considered
path_includes = [
"src/*",
]
# Commits messages with [no version] are discarded
message_excludes = [
".*\[no version\].*",
".*\[skipversion\].*",
] |
Tip
See suggested configuration examples here
Note
You can use comver with uv
by selecting the appropriate build backend,
such as hatchling.
To integrate comver with pdm
or hatch add the following to
your pyproject.toml:
| PDM | Hatch |
|---|---|
# Register comver for the build process
[build-system]
build-backend = "pdm.backend"
requires = [
"pdm-backend",
"comver>=0.1.0",
]
# Setup versioning for PDM
[tool.pdm.version]
source = "call"
getter = "comver.plugin:pdm"
# Comver-specific settings
[tool.comver]
... |
# Register comver for the build process
[build-system]
build-backend = "hatchling.build"
requires = [
"comver>=0.1.0",
"hatchling",
]
# Setup versioning for Hatchling
[tool.hatch.version]
source = "comver"
# Comver-specific settings
[tool.comver]
... |
Tip
See more in the documentation
To verify that a version was produced from the same Git tree and configuration, first use the calculate command with additional flags:
comver calculate --sha --checksumThis outputs three space-separated values:
<VERSION> <SHA> <CHECKSUM>Tip
Append --format=json for machine-friendly output
Before the next release provide these values to the comver verify
to ensure the version was previously generated from the
same codebase and config:
comver verify <VERSION> <SHA> <CHECKSUM>If inconsistencies are found, you'll receive feedback, for example:
Provided checksum and the checksum of configuration do not match.
Tip
Explore verification workflows in the tutorials
We welcome your contributions! Start here:
- This project is licensed under the Apache 2.0 License - see the LICENSE file for details.
- This project is copyrighted by open-nudge - the appropriate copyright notice is included in each file.