verbump

Version and changelog bumps for repos: only the packages that changed move.

verbump finds the packages in your repo that changed since their own last tag, writes each one's new version into its files, and turns its changelog's ## [Unreleased] notes into the release. One package or fifty, Python, Node, .NET, Java, Rust, Go or anything with a version in a file. One CLI, one verbump.toml, no dependencies.

Try it in one command: uvx --from verbump-cli verbump demo

_{A PR from feat/checkout changed only apps/web: web gets a minor bump and its release notes, api stays at 1.4.0.}

Try it in 60 seconds

With verbump installed, this builds the repo from the recording in a scratch folder and releases it:

verbump demo --dir verbump-try --setup-only && cd verbump-try
verbump status                          # api and web, both tagged; web has changes
verbump plan --branch feat/checkout     # web: 0.3.0 -> 0.4.0 (minor, tag web/v0.4.0)
verbump apply --branch feat/checkout    # writes apps/web/package.json and CHANGELOG.md
verbump notes web                       # the notes for the GitHub release

Or run verbump demo for a narrated replay in a temporary folder.

Why verbump

• Only what changed moves. Each package is released from its own last tag, so a fix in one service doesn't bump the other nine.
• Release notes you already wrote. The Unreleased notes become the version's section and the GitHub release body; with no notes, the commit subjects that touched the package.
• Any stack. It reads and writes versions in package.json, pyproject.toml, Cargo.toml, .csproj, pom.xml, Gradle, Helm charts, Dockerfiles and more, or any file you give a pattern. Go-style tags work too.
• You choose the bump. A flag, the PR's branch name, or trunk-semver's outputs. A release/<package>/X.Y.Z branch cuts an exact version.
• Safe to re-run. Tags are created once and never moved; a second run finds nothing to release.
• Nothing to run. Python 3.11+ and the standard library; no server, no plugins per language.

What it's for

Quick start

Install it. The PyPI package is verbump-cli, because the name verbump belongs to an unrelated project. The command it installs is verbump.

pipx install verbump-cli        # or: uv tool install verbump-cli, pip install verbump-cli
verbump --version

Declare your packages in verbump.toml at the repo root. verbump init writes a starter file. A minimal one looks like this:

tag_format = "{name}/v{version}"

[packages.api]
path = "services/api"
files = ["pyproject.toml", "src/api/__init__.py"]

[packages.web]
path = "apps/web"
files = ["package.json"]

See what would release. Here a commit changed services/api since its last tag api/v1.4.0, and nothing changed in apps/web:

$ verbump plan --bump minor
api: 1.4.0 -> 1.5.0 (minor, tag api/v1.5.0)

Write the new versions and changelogs. apply changes files only. It does not commit or tag.

$ verbump apply --bump minor --plan-out plan.json
api: 1.4.0 -> 1.5.0 (minor, tag api/v1.5.0)
  wrote services/api/pyproject.toml
  wrote services/api/src/api/__init__.py
  wrote services/api/CHANGELOG.md

The wrote lines go to stderr. Commit the changes, then verbump tag --plan plan.json creates the tags. For a full CI recipe, see Using it in CI.

How it works

merge PR feat/orders  ─►  trunk-semver: v0.4.0 → v0.5.0  ─►  bump = minor
                                                               │
           verbump: which packages changed since their last tag?
             services/api   (api/v1.4.0..HEAD touches it)   → 1.5.0
             apps/web       (no changes)                    → stays 0.3.0
             libs/shared    (watched by api)                → counted for api
                                                               │
   writes pyproject.toml, __init__.py, services/api/CHANGELOG.md
   commit "chore(release): api 1.5.0" → tag api/v1.5.0 → GitHub release "api 1.5.0"

The bump can come from trunk-semver, as drawn, or from --bump or a branch name. The commit, tag and release steps are your CI's job; verbump plans them and writes the files.

• What counts as a change. A package changed if any file under its path or its watch paths changed since the package's last tag, other than files that match exclude. A package with no tag yet counts every tracked file under those paths.
• Version source. Each package's version files are the source of truth. If the files and the last tag disagree, verbump bumps from the higher of the two. If a package's version files disagree with each other, verbump stops with an error.
• First release. A package with no tag yet is released at the version its files already have. A package with no version files starts from initial_version (0.0.0) and is bumped.
• Changelog. The notes under ## [Unreleased] become ## [X.Y.Z] - <date>. If nobody wrote notes, the section lists the subjects of the commits that touched the package since its last tag, leaving out chore(release) and merge commits. A missing CHANGELOG.md is created. A section for that version that already exists is left alone.
• Exact versions. A PR from release/<package>/X.Y.Z releases that package at exactly X.Y.Z, changed or not. In a single-package repo, release/X.Y.Z is enough. Use this for a new major, which bumps can't reach. An exact version must be newer than the package's last release.
• Safe to re-run. Tags point at the release commit, so a second run finds nothing new to release. If the planned tag already exists, verbump stops instead of moving it. Only the optional major tag (vX) is moved.

Configuration

verbump.toml at the repo root. Use -c <file> for another path.

tag_format = "{name}/v{version}"   # default for every package
changelog = "CHANGELOG.md"          # relative to the package path; "" for none

[packages.api]
path = "services/api"
files = ["pyproject.toml", "src/api/__init__.py"]
watch = ["libs/shared"]             # other repo paths whose changes release this package
exclude = ["*.md", "docs/*"]        # changes only here don't release it

[packages.web]
path = "apps/web"
files = ["package.json"]

Package names use letters, digits, ., _ and -. verbump rejects unknown keys.

Keys

tag_format, changelog and major_tag can be set at the top level as defaults for every package, and again per package.

For a single-package repo, use tag_format = "v{version}" and one package at path = ".". This repo's own verbump.toml is an example. examples/monorepo/verbump.toml is a monorepo with Python, Node, .NET, Maven, Go and Helm packages.

Files as tables

A file can be a table, to pick a kind for any file name or to give your own pattern:

files = [
  { path = "chart/Chart.yaml", kind = "helm" },                  # a kind for any file name
  { path = "deploy/values.yaml",                                  # or your own pattern
    pattern = 'tag:\s*"(?P<version>\d+\.\d+\.\d+)"',
    after = "image:",                                             # search only after this text
    replace_all = true },                                         # rewrite every match, not just the first
]

Supported files

verbump picks the kind of a file from its name, so most configs only list paths. Any other file needs a kind or a pattern.

A v prefix is read in Chart.yaml with kind = "helm" and in plain version files. Versions are always X.Y.Z.

Commands

verbump [-C ROOT] [-c CONFIG] <command>

Global options: -C <repo root> (default .) and -c <config file> (default <root>/verbump.toml).

Choosing the bump

plan and apply take the bump from one of these sources:

• --bump major|minor|patch.
• --previous and --version-from, which are trunk-semver's previous-version and version outputs. verbump works out the bump from the two. They go together.
• --branch <name>, which applies trunk-semver's branch rule without trunk-semver.
• Nothing, which means a patch.

--bump and --branch can't be combined. If you pass several sources, --bump wins, then --previous with --version-from, then --branch.

Other options for plan and apply

Output

plan and apply print one line per release, as name: previous -> new (reason, tag T). The previous version is - for a package with no tag. With nothing to release they print nothing to release. The reason is the bump, first release or exact.

The plan JSON has the shape {"bump", "commit_message", "releases": [{"name", "path", "previous", "version", "tag", "major_tag", "changelog", "reason", "changed"}]}.

Using it in CI

In GitHub Actions there are three actions, each in its own repo:

# on push to main
- uses: actions/checkout@v7
  with:
    fetch-depth: 0
- uses: TheKathan/verbump-release@v1

The release action takes the bump as an input from any source: trunk-semver's outputs, the merged PR's branch name (the default), or a fixed value. It doesn't run trunk-semver itself.

Anywhere else, the CLI does the same work. This recipe takes the bump from the merged PR's branch name:

verbump apply --branch "$PR_BRANCH" --release-branch "$PR_BRANCH" --plan-out plan.json
verbump check
git commit -am "$(jq -r .commit_message plan.json)"
verbump tag --plan plan.json
git push origin HEAD:main --follow-tags

--follow-tags pushes the annotated tags. Major tags are lightweight and moved, so push them yourself, for example with git push --force origin <major_tag>. To create a GitHub release for each package, loop over the plan and use verbump notes <name> <version> as the release body.

This repo releases itself with .github/workflows/release.yml, running verbump from its own source. It runs in this order:

1. Run trunk-semver against a local mirror, so its repo-wide tag never reaches GitHub, and take the bump from its previous-version and version. When it gives no previous version, use the PR's branch name.
2. Run verbump apply and verbump check.
3. Commit, tag and push.
4. Publish the GitHub release.
5. Build the sdist and the wheel.
6. Upload them to PyPI, when the PUBLISH_PYPI variable is true.

Contribute

Bugs, questions and ideas go to issues, and pull requests are welcome: see CONTRIBUTING and the code of conduct. Issues about one of the GitHub Actions go to its repo: verbump-release, verbump-check or setup-verbump. If verbump saves you a release chore, a star helps others find it.

CHANGELOG · SECURITY · Publishing · LICENSE (MIT)