verbump-cli 1.0.0__py3-none-any.whl

verbump/__init__.py

@@ -0,0 +1,3 @@
+"""verbump: version and changelog bumps for repos."""
+
+__version__ = "1.0.0"

verbump/__main__.py

@@ -0,0 +1,3 @@
+from verbump.cli import main
+
+main()

verbump/changelog.py

@@ -0,0 +1,53 @@
+"""Keep a Changelog files: turn "Unreleased" into a version section, and read a section back.
+
+The notes written under "## [Unreleased]" become the release. When nobody wrote any, the
+section lists the commit subjects that touched the package since its last release.
+"""
+
+import re
+
+HEADER = (
+    "# Changelog\n\n"
+    "All notable changes are listed here. The format follows "
+    "[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow "
+    "[Semantic Versioning](https://semver.org/).\n\n"
+    "## [Unreleased]\n"
+)
+UNRELEASED = re.compile(r"^## \[Unreleased\][^\n]*\n", re.MULTILINE)
+ANY_SECTION = re.compile(r"^## \[", re.MULTILINE)
+SKIP_SUBJECT = re.compile(r"^(chore\(release\)|Merge )")
+
+
+def section_re(version: str) -> re.Pattern:
+    return re.compile(rf"^## \[{re.escape(version)}\][^\n]*\n(.*?)(?=^## \[|\Z)", re.DOTALL | re.MULTILINE)
+
+
+def commit_entries(commits: list[tuple[str, str]]) -> str:
+    lines = [f"- {subject} ({sha})" for sha, subject in commits if not SKIP_SUBJECT.match(subject)]
+    return "### Changes\n" + "\n".join(lines) + "\n" if lines else ""
+
+
+def release(text: str | None, version: str, date: str, commits: list[tuple[str, str]]) -> str:
+    """The changelog with a `## [version] - date` section; unchanged if that section exists."""
+    text = text if text is not None else HEADER
+    if section_re(version).search(text):
+        return text
+    m = UNRELEASED.search(text)
+    if m:
+        nxt = ANY_SECTION.search(text, m.end())
+        body_end = nxt.start() if nxt else len(text)
+        body = text[m.end():body_end].strip()
+        head, rest = text[:m.end()], text[body_end:]
+    else:
+        nxt = ANY_SECTION.search(text)
+        cut = nxt.start() if nxt else len(text)
+        body = ""
+        head, rest = text[:cut].rstrip("\n") + "\n\n## [Unreleased]\n", text[cut:]
+    body = body or commit_entries(commits).strip() or "No notable changes."
+    section = f"\n## [{version}] - {date}\n\n{body}\n"
+    return head + section + ("\n" + rest if rest else "")
+
+
+def notes(text: str, version: str) -> str:
+    m = section_re(version).search(text or "")
+    return (m.group(1).strip() if m else "") or f"Release {version}."

verbump/cli.py

@@ -0,0 +1,237 @@
+"""verbump command line.
+
+  verbump status                               packages, versions, last tags, pending changes
+  verbump plan  --previous v1.4.0 --version-from v1.5.0   what would release (trunk-semver outputs)
+  verbump apply --bump minor --plan-out plan.json      write versions and changelogs
+  verbump tag   --plan plan.json               create the planned git tags
+  verbump notes <package> [<version>]          a version's changelog section, for a release body
+  verbump set   <package> <version>            write an exact version into one package
+  verbump check                                exit 1 if a package's version files disagree
+  verbump init                                 write a starter verbump.toml
+  verbump demo                                 a narrated release in a throwaway repo
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from verbump import __version__, changelog, gitutil, release, semver
+from verbump.config import Config, ConfigError, load
+
+STARTER = '''\
+# verbump: one table per package that has its own version.
+# Tags are "<name>/v<version>" unless tag_format says otherwise.
+tag_format = "{name}/v{version}"
+changelog = "CHANGELOG.md"
+
+[packages.app]
+path = "."
+files = ["pyproject.toml"]
+# watch = ["libs/shared"]        # changes here also release this package
+# exclude = ["*.md", "docs/*"]   # changes only here don't
+'''
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = parser().parse_args(argv)
+    try:
+        code = args.func(args)
+    except (ConfigError, release.ReleaseError, semver.VersionError, gitutil.GitError, ValueError) as e:
+        sys.exit(f"verbump: {e}")
+    sys.exit(code or 0)
+
+
+def parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="verbump", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--version", action="version", version=f"verbump {__version__}")
+    p.add_argument("-C", "--root", type=Path, default=Path("."), help="repo root (default: .)")
+    p.add_argument("-c", "--config", type=Path, help="config file (default: <root>/verbump.toml)")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    s = sub.add_parser("status", help="show every package")
+    s.add_argument("--json", action="store_true")
+    s.set_defaults(func=cmd_status)
+
+    for name, func, help_ in (("plan", cmd_plan, "show what would release"),
+                              ("apply", cmd_apply, "write the versions and changelogs")):
+        s = sub.add_parser(name, help=help_)
+        src = s.add_mutually_exclusive_group()
+        src.add_argument("--bump", choices=semver.BUMPS, type=str.lower, help="bump every changed package by this")
+        src.add_argument("--branch", help="pick the bump from a branch name, like trunk-semver")
+        s.add_argument("--previous", help="trunk-semver previous-version; with --version-from, gives the bump")
+        s.add_argument("--version-from", dest="new_version", metavar="VERSION",
+                       help="trunk-semver version output (the new version)")
+        s.add_argument("--exact", action="append", default=[], metavar="NAME=X.Y.Z",
+                       help="release a package at exactly this version, changed or not")
+        s.add_argument("--release-branch", metavar="BRANCH",
+                       help="release/<package>/X.Y.Z (or release/X.Y.Z with one package) sets --exact")
+        s.add_argument("--only", action="append", default=[], metavar="NAME", help="limit to these packages")
+        s.add_argument("--json", action="store_true", help="print the plan as JSON")
+        s.add_argument("--plan-out", type=Path, help="also write the plan as JSON to this file")
+        if name == "apply":
+            s.add_argument("--date", help="release date (default: today, UTC)")
+        s.set_defaults(func=func)
+
+    s = sub.add_parser("tag", help="create the git tags of a plan")
+    s.add_argument("--plan", type=Path, required=True)
+    s.set_defaults(func=cmd_tag)
+
+    s = sub.add_parser("notes", help="print a version's changelog section")
+    s.add_argument("package")
+    s.add_argument("version", nargs="?")
+    s.set_defaults(func=cmd_notes)
+
+    s = sub.add_parser("set", help="write an exact version into one package's files and changelog")
+    s.add_argument("package")
+    s.add_argument("version")
+    s.add_argument("--date")
+    s.set_defaults(func=cmd_set)
+
+    s = sub.add_parser("check", help="exit 1 if a package's version files disagree")
+    s.set_defaults(func=cmd_check)
+
+    s = sub.add_parser("init", help="write a starter verbump.toml")
+    s.set_defaults(func=cmd_init)
+
+    s = sub.add_parser("demo", help="a narrated release in a throwaway repo")
+    s.add_argument("--dir", type=Path, help="build the demo repo here and keep it (an empty or new folder)")
+    s.add_argument("--setup-only", action="store_true", help="only build the demo repo and print its path")
+    s.set_defaults(func=cmd_demo)
+    return p
+
+
+def config(args) -> Config:
+    return load(args.config or args.root / "verbump.toml")
+
+
+def resolve_bump(args) -> str:
+    if args.bump:
+        return args.bump
+    if args.previous or args.new_version:
+        if not (args.previous and args.new_version):
+            raise ValueError("--previous and --version-from go together")
+        return semver.bump_between(args.previous, args.new_version)
+    if args.branch:
+        return semver.bump_for_branch(args.branch)
+    return "patch"
+
+
+def build_plan(args):
+    cfg = config(args)
+    bump = resolve_bump(args)
+    exact = release.exact_from_branch(cfg, args.release_branch)
+    for item in args.exact:
+        name, sep, version = item.partition("=")
+        if not sep:
+            raise ValueError(f"--exact {item!r}: use NAME=X.Y.Z")
+        exact[name] = version
+    releases = release.plan(args.root, cfg, bump, exact, args.only)
+    return cfg, bump, releases
+
+
+def report(args, cfg, bump, releases) -> None:
+    data = release.to_json(cfg, bump, releases)
+    if args.plan_out:
+        args.plan_out.write_text(json.dumps(data, indent=2) + "\n")
+    if args.json:
+        print(json.dumps(data, indent=2))
+    elif not releases:
+        print("nothing to release")
+    else:
+        for r in releases:
+            print(f"{r.name}: {r.previous or '-'} -> {r.version} ({r.reason}, tag {r.tag})")
+
+
+def cmd_plan(args) -> int:
+    report(args, *build_plan(args))
+    return 0
+
+
+def cmd_apply(args) -> int:
+    cfg, bump, releases = build_plan(args)
+    touched = release.apply(args.root, cfg, releases, args.date)
+    report(args, cfg, bump, releases)
+    for path in touched:
+        print(f"  wrote {path}", file=sys.stderr)
+    return 0
+
+
+def cmd_tag(args) -> int:
+    data = json.loads(args.plan.read_text())
+    for r in data["releases"]:
+        gitutil.git(args.root, "tag", "-a", r["tag"], "-m", f"{r['name']} {r['version']}")
+        print(r["tag"])
+        if r.get("major_tag"):
+            gitutil.git(args.root, "tag", "-f", r["major_tag"])
+            print(r["major_tag"])
+    return 0
+
+
+def cmd_notes(args) -> int:
+    cfg = config(args)
+    pkg = cfg.get(args.package)
+    version = semver.normalize(args.version) if args.version else release.file_version(args.root, pkg)
+    if not version:
+        raise ValueError(f"{pkg.name} has no version files; pass the version")
+    path = args.root / pkg.changelog_path if pkg.changelog_path else None
+    print(changelog.notes(path.read_text() if path and path.is_file() else "", version))
+    return 0
+
+
+def cmd_set(args) -> int:
+    cfg = config(args)
+    pkg = cfg.get(args.package)
+    version = semver.normalize(args.version)
+    r = release.Release(name=pkg.name, path=pkg.path, previous=None, version=version, tag=pkg.tag(version),
+                        major_tag=None, changelog=pkg.changelog_path, reason="set")
+    release.apply(args.root, cfg, [r], args.date)
+    print(f"set {pkg.name} {version}")
+    return 0
+
+
+def cmd_check(args) -> int:
+    cfg = config(args)
+    bad = 0
+    for pkg in cfg.packages:
+        try:
+            v = release.file_version(args.root, pkg)
+            print(f"{pkg.name}: {v or 'no version files'}")
+        except (release.ReleaseError, ValueError) as e:
+            print(f"{pkg.name}: {e}", file=sys.stderr)
+            bad += 1
+    return 1 if bad else 0
+
+
+def cmd_status(args) -> int:
+    cfg = config(args)
+    tags = gitutil.tags_merged(args.root)
+    rows = []
+    for pkg in cfg.packages:
+        st = release.state(args.root, pkg, tags)
+        rows.append({"name": pkg.name, "path": pkg.path, "version": st.file_version, "last_tag": st.last_tag,
+                     "changed": len(st.changed)})
+    if args.json:
+        print(json.dumps(rows, indent=2))
+    else:
+        table = [(r["name"], r["path"], r["version"] or "-", r["last_tag"] or "(no tag)", f"{r['changed']} changed")
+                 for r in rows]
+        widths = [max(len(row[i]) for row in table) for i in range(4)]
+        for row in table:
+            print("  ".join(cell.ljust(w) for cell, w in zip(row[:4], widths, strict=True)) + "  " + row[4])
+    return 0
+
+
+def cmd_init(args) -> int:
+    path = args.config or args.root / "verbump.toml"
+    if path.exists():
+        raise ValueError(f"{path} already exists")
+    path.write_text(STARTER)
+    print(f"wrote {path}")
+    return 0
+
+
+def cmd_demo(args) -> int:
+    from verbump import demo
+
+    return demo.main(keep=args.dir, setup_only=args.setup_only)

verbump/config.py

@@ -0,0 +1,158 @@
+"""Load verbump.toml.
+
+    tag_format = "{name}/v{version}"     # defaults for every package
+    changelog = "CHANGELOG.md"            # relative to the package path
+
+    [packages.api]
+    path = "services/api"
+    files = ["pyproject.toml", { path = "deploy/values.yaml", pattern = 'tag: "(?P<version>[0-9.]+)"' }]
+    watch = ["libs/shared"]               # more repo paths whose changes release this package
+    exclude = ["*.md", "docs/**"]         # changes here alone don't release it
+"""
+
+import posixpath
+import re
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from verbump.files import VersionFile, version_file
+
+DEFAULT_TAG_FORMAT = "{name}/v{version}"
+DEFAULT_COMMIT = "chore(release): {releases}"
+NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+PACKAGE_KEYS = {"path", "files", "watch", "exclude", "tag_format", "changelog", "major_tag", "initial_version"}
+FILE_KEYS = {"path", "kind", "pattern", "after", "replace_all"}
+TOP_KEYS = {"tag_format", "changelog", "commit_message", "major_tag", "packages"}
+
+
+class ConfigError(ValueError):
+    pass
+
+
+@dataclass
+class Package:
+    name: str
+    path: str
+    files: list[VersionFile]
+    watch: list[str] = field(default_factory=list)
+    exclude: list[str] = field(default_factory=list)
+    tag_format: str = DEFAULT_TAG_FORMAT
+    changelog: str | None = "CHANGELOG.md"
+    major_tag: bool = False
+    initial_version: str = "0.0.0"
+
+    def repo_path(self, rel: str) -> str:
+        return posixpath.normpath(posixpath.join(self.path, rel))
+
+    @property
+    def changelog_path(self) -> str | None:
+        return self.repo_path(self.changelog) if self.changelog else None
+
+    @property
+    def paths(self) -> list[str]:
+        return [self.path, *self.watch]
+
+    def tag(self, version: str) -> str:
+        return self.tag_format.format(name=self.name, path=self.path, version=version)
+
+    def major_tag_name(self, version: str) -> str:
+        return self.tag(version).rsplit(version, 1)[0] + version.split(".")[0]
+
+    def tag_regex(self) -> re.Pattern:
+        head, _, tail = self.tag_format.partition("{version}")
+        return re.compile(
+            "^" + re.escape(head.format(name=self.name, path=self.path)) + r"(?P<version>\d+\.\d+\.\d+)"
+            + re.escape(tail.format(name=self.name, path=self.path)) + "$"
+        )
+
+
+@dataclass
+class Config:
+    packages: list[Package]
+    commit_message: str = DEFAULT_COMMIT
+
+    def get(self, name: str) -> Package:
+        for p in self.packages:
+            if p.name == name:
+                return p
+        raise ConfigError(f"no package named {name!r} (known: {', '.join(p.name for p in self.packages)})")
+
+
+def load(path: Path) -> Config:
+    if not path.is_file():
+        raise ConfigError(f"{path}: not found (create a verbump.toml, see `verbump init`)")
+    try:
+        data = tomllib.loads(path.read_text())
+    except tomllib.TOMLDecodeError as e:
+        raise ConfigError(f"{path}: {e}") from e
+    return parse(data)
+
+
+def parse(data: dict) -> Config:
+    unknown = set(data) - TOP_KEYS
+    if unknown:
+        raise ConfigError(f"unknown top-level keys: {', '.join(sorted(unknown))}")
+    raw = data.get("packages")
+    if not isinstance(raw, dict) or not raw:
+        raise ConfigError("no [packages.<name>] tables")
+    defaults = {k: data[k] for k in ("tag_format", "changelog", "major_tag") if k in data}
+    packages = [_package(name, {**defaults, **spec}) for name, spec in raw.items()]
+    _check_unique_tags(packages)
+    return Config(packages=packages, commit_message=data.get("commit_message", DEFAULT_COMMIT))
+
+
+def _package(name: str, spec: dict) -> Package:
+    if not NAME_RE.match(name):
+        raise ConfigError(f"package name {name!r}: use letters, digits, '.', '_' or '-'")
+    unknown = set(spec) - PACKAGE_KEYS
+    if unknown:
+        raise ConfigError(f"[packages.{name}]: unknown keys {', '.join(sorted(unknown))}")
+    path = posixpath.normpath(spec.get("path", "."))
+    if path.startswith(("..", "/")):
+        raise ConfigError(f"[packages.{name}]: path must stay inside the repo")
+    tag_format = spec.get("tag_format", DEFAULT_TAG_FORMAT)
+    if tag_format.count("{version}") != 1:
+        raise ConfigError(f"[packages.{name}]: tag_format needs exactly one {{version}}")
+    try:
+        tag_format.format(name=name, path=path, version="0.0.0")
+    except (KeyError, IndexError, ValueError) as e:
+        raise ConfigError(f"[packages.{name}]: tag_format may use only {{name}}, {{path}} and {{version}}") from e
+    if "{path}" in tag_format and path == ".":
+        raise ConfigError(f"[packages.{name}]: a package at the repo root can't use {{path}} in tag_format")
+    files = []
+    for f in spec.get("files", []):
+        if isinstance(f, str):
+            f = {"path": f}
+        if not isinstance(f, dict) or "path" not in f:
+            raise ConfigError(f"[packages.{name}]: each file is a path or {{ path, kind | pattern, ... }}")
+        if unknown := set(f) - FILE_KEYS:
+            raise ConfigError(f"[packages.{name}] file {f['path']}: unknown keys {', '.join(sorted(unknown))}")
+        rel = posixpath.normpath(posixpath.join(path, f["path"]))
+        try:
+            vf = version_file(rel, f.get("kind"), f.get("pattern"), f.get("after"), f.get("replace_all"))
+            vf.regex()
+            files.append(vf)
+        except ValueError as e:
+            raise ConfigError(f"[packages.{name}]: {e}") from e
+    changelog = spec.get("changelog", "CHANGELOG.md")
+    return Package(
+        name=name,
+        path=path,
+        files=files,
+        watch=[posixpath.normpath(w) for w in spec.get("watch", [])],
+        exclude=list(spec.get("exclude", [])),
+        tag_format=tag_format,
+        changelog=changelog or None,
+        major_tag=bool(spec.get("major_tag", False)),
+        initial_version=spec.get("initial_version", "0.0.0"),
+    )
+
+
+def _check_unique_tags(packages: list[Package]) -> None:
+    seen = {}
+    for p in packages:
+        probe = p.tag("1.2.3")
+        if probe in seen:
+            raise ConfigError(f"packages {seen[probe]!r} and {p.name!r} would share tags; give one its own tag_format")
+        seen[probe] = p.name

verbump/demo.py

@@ -0,0 +1,101 @@
+"""`verbump demo`: a narrated release in a throwaway repo with a Python and a Node package."""
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import textwrap
+from pathlib import Path
+
+CONFIG = """\
+[packages.api]
+path = "services/api"
+files = ["pyproject.toml"]
+
+[packages.web]
+path = "apps/web"
+files = ["package.json"]
+"""
+
+GIT = ["git", "-c", "user.name=demo", "-c", "user.email=demo@example.com", "-c", "commit.gpgsign=false",
+       "-c", "tag.gpgsign=false", "-c", "init.defaultBranch=main"]
+
+
+def git(root: Path, *args: str) -> str:
+    return subprocess.run([*GIT, *args], cwd=root, check=True, capture_output=True, text=True).stdout
+
+
+def write(root: Path, path: str, text: str) -> None:
+    p = root / path
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(text)
+
+
+def changelog(*sections: str) -> str:
+    return "# Changelog\n\n## [Unreleased]\n" + "".join(sections)
+
+
+def setup(root: Path) -> None:
+    """Build the demo repo: api 1.4.0 and web 0.3.0 released, then a PR that changed web."""
+    root.mkdir(parents=True, exist_ok=True)
+    git(root, "init", "-q")
+    write(root, "verbump.toml", CONFIG)
+    write(root, "services/api/pyproject.toml", '[project]\nname = "api"\nversion = "1.4.0"\n')
+    write(root, "services/api/app.py", "def health():\n    return 'ok'\n")
+    write(root, "services/api/CHANGELOG.md", changelog("\n## [1.4.0] - 2026-11-02\n\n- Health check.\n"))
+    write(root, "apps/web/package.json", json.dumps({"name": "web", "version": "0.3.0"}, indent=2) + "\n")
+    write(root, "apps/web/index.js", "export const home = () => 'home'\n")
+    write(root, "apps/web/CHANGELOG.md", changelog("\n## [0.3.0] - 2026-11-02\n\n- Home page.\n"))
+    git(root, "add", "-A")
+    git(root, "commit", "-qm", "chore(release): api 1.4.0, web 0.3.0")
+    git(root, "tag", "api/v1.4.0")
+    git(root, "tag", "web/v0.3.0")
+    write(root, "apps/web/checkout.js", "export const checkout = () => 'pay'\n")
+    write(root, "apps/web/CHANGELOG.md", changelog("\n### Added\n- Checkout page.\n",
+                                                   "\n## [0.3.0] - 2026-11-02\n\n- Home page.\n"))
+    git(root, "add", "-A")
+    git(root, "commit", "-qm", "feat(web): checkout page")
+
+
+def run(root: Path, *args: str) -> None:
+    print(f"$ {' '.join(args)}", flush=True)
+    cmd = [sys.executable, "-m", "verbump", *args[1:]] if args[0] == "verbump" else [*GIT, *args[1:]]
+    pkg_root = str(Path(__file__).resolve().parent.parent)
+    env = {**os.environ, "PYTHONPATH": os.pathsep.join(filter(None, [pkg_root, os.environ.get("PYTHONPATH")]))}
+    proc = subprocess.run(cmd, cwd=root, capture_output=True, text=True, check=False, env=env)
+    out = (proc.stdout + proc.stderr).rstrip()
+    if out:
+        print(out)
+    print()
+
+
+def say(text: str) -> None:
+    print(textwrap.fill(f"# {text}", width=88, subsequent_indent="# "))
+
+
+def main(keep: Path | None = None, setup_only: bool = False) -> int:
+    root = keep or Path(tempfile.mkdtemp(prefix="verbump-demo-"))
+    if keep and keep.exists() and any(keep.iterdir()):
+        raise ValueError(f"{keep} is not empty")
+    setup(root)
+    if setup_only:
+        print(root)
+        return 0
+    try:
+        say("A repo with two packages: api (Python) at 1.4.0 and web (Node) at 0.3.0, both tagged.")
+        say("A PR from feat/checkout just changed apps/web and wrote a note under Unreleased.")
+        print()
+        run(root, "verbump", "status")
+        say("feat/* is a minor bump. Only web changed since its tag, so only web moves.")
+        run(root, "verbump", "plan", "--branch", "feat/checkout")
+        run(root, "verbump", "apply", "--branch", "feat/checkout", "--date", "2026-11-09")
+        say("The version and the changelog, written:")
+        run(root, "git", "diff", "--stat")
+        run(root, "verbump", "notes", "web")
+        say("CI then commits, runs `verbump tag`, pushes, and uses those notes as the GitHub release.")
+    finally:
+        if keep is None:
+            shutil.rmtree(root, ignore_errors=True)
+    return 0

verbump/files.py

@@ -0,0 +1,149 @@
+"""Read and write the version inside the files that carry it.
+
+A file is matched by a regex with a named group `version`. Files of the common stacks get a
+kind from their name, so most configs only list paths. Any file can name a `kind`, or set
+its own `pattern`, optionally searched only `after` a marker and rewritten at every match.
+"""
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+V = r"\d+\.\d+\.\d+"
+
+
+@dataclass(frozen=True)
+class Kind:
+    pattern: str
+    after: str | None = None
+    replace_all: bool = False
+
+
+KINDS = {
+    "toml": Kind(rf'(?m)^version\s*=\s*"(?P<version>{V})"'),
+    "json": Kind(rf'"version"\s*:\s*"(?P<version>{V})"'),
+    "yaml": Kind(rf"(?m)^version:\s*['\"]?(?P<version>{V})"),
+    "helm": Kind(rf"(?m)^(?:version|appVersion):\s*['\"]?v?(?P<version>{V})", replace_all=True),
+    "plain": Kind(rf"\A\s*v?(?P<version>{V})"),
+    "python": Kind(rf"__version__\s*=\s*['\"](?P<version>{V})['\"]"),
+    "msbuild": Kind(rf"<(?:Version|VersionPrefix)>(?P<version>{V})</"),
+    "assemblyinfo": Kind(rf'Assembly(?:File|Informational)?Version\(\s*"(?P<version>{V})', replace_all=True),
+    "maven": Kind(rf"<version>(?P<version>{V})</version>", after="</parent>"),
+    "properties": Kind(rf"(?m)^version\s*[=:]\s*(?P<version>{V})"),
+    "gradle": Kind(rf"""(?m)^\s*version\s*=?\s*["'](?P<version>{V})["']"""),
+    "ruby": Kind(rf"""(?:VERSION|\.version)\s*=\s*["'](?P<version>{V})["']"""),
+    "elixir": Kind(rf'version:\s*"(?P<version>{V})"'),
+    "dockerfile": Kind(rf"""(?im)^LABEL\s.*?version\s*=\s*["']?(?P<version>{V})"""),
+}
+
+BY_NAME = {
+    "pyproject.toml": "toml",
+    "Cargo.toml": "toml",
+    "package.json": "json",
+    "composer.json": "json",
+    "deno.json": "json",
+    "jsr.json": "json",
+    "manifest.json": "json",
+    "Chart.yaml": "yaml",
+    "pubspec.yaml": "yaml",
+    "VERSION": "plain",
+    "VERSION.txt": "plain",
+    "version.txt": "plain",
+    ".version": "plain",
+    "AssemblyInfo.cs": "assemblyinfo",
+    "pom.xml": "maven",
+    "gradle.properties": "properties",
+    "setup.cfg": "properties",
+    "build.gradle": "gradle",
+    "build.gradle.kts": "gradle",
+    "version.rb": "ruby",
+    "mix.exs": "elixir",
+    "Dockerfile": "dockerfile",
+}
+BY_SUFFIX = {
+    ".py": "python",
+    ".csproj": "msbuild",
+    ".fsproj": "msbuild",
+    ".vbproj": "msbuild",
+    ".props": "msbuild",
+    ".gemspec": "ruby",
+}
+
+
+class VersionFileError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class VersionFile:
+    path: str
+    pattern: str
+    after: str | None = None
+    replace_all: bool = False
+
+    def regex(self) -> re.Pattern:
+        rx = re.compile(self.pattern)
+        if "version" not in rx.groupindex:
+            raise VersionFileError(f"{self.path}: pattern has no (?P<version>...) group")
+        return rx
+
+    def read(self, root: Path) -> str:
+        text = self._text(root)
+        return self._matches(text)[0].group("version")
+
+    def write(self, root: Path, version: str) -> bool:
+        text = self._text(root)
+        matches = self._matches(text)
+        if not self.replace_all:
+            matches = matches[:1]
+        new = text
+        for m in reversed(matches):
+            start, end = m.span("version")
+            new = new[:start] + version + new[end:]
+        if new == text:
+            return False
+        (root / self.path).write_text(new)
+        return True
+
+    def _matches(self, text: str) -> list[re.Match]:
+        start = 0
+        if self.after and (i := text.find(self.after)) >= 0:
+            start = i + len(self.after)
+        matches = list(self.regex().finditer(text, start))
+        if not matches:
+            raise VersionFileError(f"{self.path}: no version matches {self.pattern!r}")
+        return matches
+
+    def _text(self, root: Path) -> str:
+        p = root / self.path
+        if not p.is_file():
+            raise VersionFileError(f"{self.path}: file not found")
+        return p.read_text()
+
+
+def kind_for(path: str) -> str:
+    name, suffix = Path(path).name, Path(path).suffix
+    if name in BY_NAME:
+        return BY_NAME[name]
+    if suffix in BY_SUFFIX:
+        return BY_SUFFIX[suffix]
+    raise VersionFileError(
+        f"{path}: unknown file type; set `kind` (one of {', '.join(KINDS)}) or a `pattern` with a (?P<version>...) group"
+    )
+
+
+def version_file(path: str, kind: str | None = None, pattern: str | None = None, after: str | None = None,
+                 replace_all: bool | None = None) -> VersionFile:
+    """A version file from its config: an explicit pattern wins, then the kind, then the file name."""
+    base = None
+    if not pattern:
+        name = kind or kind_for(path)
+        if name not in KINDS:
+            raise VersionFileError(f"{path}: unknown kind {name!r}; use one of {', '.join(KINDS)}")
+        base = KINDS[name]
+    return VersionFile(
+        path=path,
+        pattern=pattern or base.pattern,
+        after=after if after is not None else (base.after if base else None),
+        replace_all=replace_all if replace_all is not None else (base.replace_all if base else False),
+    )

verbump/gitutil.py

@@ -0,0 +1,39 @@
+"""Thin wrappers around the git commands verbump needs."""
+
+import subprocess
+from pathlib import Path
+
+
+class GitError(RuntimeError):
+    pass
+
+
+def git(root: Path, *args: str) -> str:
+    proc = subprocess.run(["git", *args], cwd=root, capture_output=True, text=True, check=False)
+    if proc.returncode != 0:
+        raise GitError(f"git {' '.join(args)}: {proc.stderr.strip()}")
+    return proc.stdout
+
+
+def tags_merged(root: Path) -> list[str]:
+    return git(root, "tag", "--merged", "HEAD").split()
+
+
+def tag_exists(root: Path, tag: str) -> bool:
+    return bool(git(root, "tag", "--list", tag).strip())
+
+
+def changed_files(root: Path, base: str | None, paths: list[str]) -> list[str]:
+    """Files changed under `paths` since `base`; every tracked file under them when there is no base."""
+    if base is None:
+        out = git(root, "ls-files", "--", *paths)
+    else:
+        out = git(root, "diff", "--name-only", f"{base}..HEAD", "--", *paths)
+    return [line for line in out.splitlines() if line]
+
+
+def log_subjects(root: Path, base: str | None, paths: list[str]) -> list[tuple[str, str]]:
+    """(short sha, subject) of the commits touching `paths` since `base`, oldest first."""
+    rng = [f"{base}..HEAD"] if base else ["HEAD"]
+    out = git(root, "log", "--reverse", "--no-merges", "--format=%h%x09%s", *rng, "--", *paths)
+    return [tuple(line.split("\t", 1)) for line in out.splitlines() if "\t" in line]

verbump/release.py

@@ -0,0 +1,152 @@
+"""Work out which packages release and at what version, then write it."""
+
+import datetime
+import fnmatch
+import posixpath
+import re
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+from verbump import changelog, gitutil, semver
+from verbump.config import Config, Package
+
+RELEASE_BRANCH = re.compile(r"^release/(?:(?P<name>[^/]+)/)?v?(?P<version>\d+\.\d+\.\d+)$")
+
+
+class ReleaseError(RuntimeError):
+    pass
+
+
+@dataclass
+class State:
+    package: Package
+    file_version: str | None
+    last_tag: str | None
+    last_version: str | None
+    changed: list[str]
+
+    @property
+    def current(self) -> str | None:
+        known = [v for v in (self.file_version, self.last_version) if v]
+        return max(known, key=semver.parse) if known else None
+
+
+@dataclass
+class Release:
+    name: str
+    path: str
+    previous: str | None
+    version: str
+    tag: str
+    major_tag: str | None
+    changelog: str | None
+    reason: str
+    changed: list[str] = field(default_factory=list)
+
+
+def last_release(root: Path, pkg: Package, tags: list[str]) -> tuple[str | None, str | None]:
+    rx = pkg.tag_regex()
+    found = [(semver.parse(m.group("version")), t, m.group("version")) for t in tags if (m := rx.match(t))]
+    if not found:
+        return None, None
+    _, tag, version = max(found)
+    return tag, version
+
+
+def file_version(root: Path, pkg: Package) -> str | None:
+    versions = {f.path: f.read(root) for f in pkg.files}
+    if len(set(versions.values())) > 1:
+        raise ReleaseError(f"{pkg.name}: version files disagree: {versions}")
+    return next(iter(versions.values()), None)
+
+
+def excluded(pkg: Package, path: str) -> bool:
+    rel = posixpath.relpath(path, pkg.path) if pkg.path != "." else path
+    return any(fnmatch.fnmatch(path, pat) or fnmatch.fnmatch(rel, pat) for pat in pkg.exclude)
+
+
+def state(root: Path, pkg: Package, tags: list[str]) -> State:
+    tag, version = last_release(root, pkg, tags)
+    files = gitutil.changed_files(root, tag, pkg.paths)
+    return State(pkg, file_version(root, pkg), tag, version, [f for f in files if not excluded(pkg, f)])
+
+
+def exact_from_branch(cfg: Config, branch: str | None) -> dict[str, str]:
+    m = RELEASE_BRANCH.match(branch or "")
+    if not m:
+        return {}
+    name = m.group("name")
+    if name is None:
+        if len(cfg.packages) != 1:
+            raise ReleaseError(f"{branch}: name the package, e.g. release/<package>/{m.group('version')}")
+        name = cfg.packages[0].name
+    cfg.get(name)
+    return {name: m.group("version")}
+
+
+def plan(root: Path, cfg: Config, bump: str, exact: dict[str, str] | None = None,
+         only: list[str] | None = None) -> list[Release]:
+    exact = {k: semver.normalize(v) for k, v in (exact or {}).items()}
+    for name in [*exact, *(only or [])]:
+        cfg.get(name)
+    tags = gitutil.tags_merged(root)
+    releases = []
+    for pkg in cfg.packages:
+        if only and pkg.name not in only:
+            continue
+        st = state(root, pkg, tags)
+        if pkg.name in exact:
+            version, reason = exact[pkg.name], "exact"
+            if st.last_version and semver.parse(version) <= semver.parse(st.last_version):
+                raise ReleaseError(f"{pkg.name}: {version} is not newer than the last release {st.last_version}")
+        elif not st.changed:
+            continue
+        elif st.last_tag is None and st.file_version:
+            version, reason = st.file_version, "first release"
+        elif st.last_tag is None:
+            version, reason = semver.bump(pkg.initial_version, bump), "first release"
+        else:
+            version, reason = semver.bump(st.current, bump), bump
+        tag = pkg.tag(version)
+        if gitutil.tag_exists(root, tag):
+            raise ReleaseError(f"{pkg.name}: tag {tag} already exists")
+        releases.append(Release(
+            name=pkg.name, path=pkg.path, previous=st.last_version, version=version, tag=tag,
+            major_tag=pkg.major_tag_name(version) if pkg.major_tag else None,
+            changelog=pkg.changelog_path, reason=reason, changed=st.changed,
+        ))
+    return releases
+
+
+def apply(root: Path, cfg: Config, releases: list[Release], date: str | None = None) -> list[str]:
+    """Write every release into its files and changelog; returns the paths it changed."""
+    date = date or datetime.datetime.now(datetime.UTC).date().isoformat()
+    tags = gitutil.tags_merged(root)
+    touched = []
+    for r in releases:
+        pkg = cfg.get(r.name)
+        for f in pkg.files:
+            if f.write(root, r.version):
+                touched.append(f.path)
+        if pkg.changelog_path:
+            last_tag, _ = last_release(root, pkg, tags)
+            path = root / pkg.changelog_path
+            old = path.read_text() if path.is_file() else None
+            new = changelog.release(old, r.version, date, gitutil.log_subjects(root, last_tag, pkg.paths))
+            if new != old:
+                path.parent.mkdir(parents=True, exist_ok=True)
+                path.write_text(new)
+                touched.append(pkg.changelog_path)
+    return touched
+
+
+def commit_message(cfg: Config, releases: list[Release]) -> str:
+    return cfg.commit_message.format(releases=", ".join(f"{r.name} {r.version}" for r in releases))
+
+
+def to_json(cfg: Config, bump: str, releases: list[Release]) -> dict:
+    return {
+        "bump": bump,
+        "commit_message": commit_message(cfg, releases) if releases else "",
+        "releases": [asdict(r) for r in releases],
+    }

verbump/semver.py

@@ -0,0 +1,50 @@
+"""Plain X.Y.Z versions: parse, compare and bump."""
+
+import re
+
+SEMVER = re.compile(r"^v?(\d+)\.(\d+)\.(\d+)$")
+BUMPS = ("major", "minor", "patch")
+
+
+class VersionError(ValueError):
+    pass
+
+
+def parse(text: str) -> tuple[int, int, int]:
+    m = SEMVER.match(text.strip())
+    if not m:
+        raise VersionError(f"not an X.Y.Z version: {text!r}")
+    return int(m.group(1)), int(m.group(2)), int(m.group(3))
+
+
+def normalize(text: str) -> str:
+    return ".".join(map(str, parse(text)))
+
+
+def bump(version: str, kind: str) -> str:
+    major, minor, patch = parse(version)
+    kind = kind.lower()
+    if kind == "major":
+        return f"{major + 1}.0.0"
+    if kind == "minor":
+        return f"{major}.{minor + 1}.0"
+    if kind == "patch":
+        return f"{major}.{minor}.{patch + 1}"
+    raise VersionError(f"unknown bump {kind!r}; use one of {', '.join(BUMPS)}")
+
+
+def bump_between(previous: str, new: str) -> str:
+    """The bump that turns `previous` into `new`, e.g. trunk-semver's previous-version and version."""
+    p, n = parse(previous), parse(new)
+    if n <= p:
+        raise VersionError(f"{new} is not newer than {previous}")
+    if n[0] != p[0]:
+        return "major"
+    if n[1] != p[1]:
+        return "minor"
+    return "patch"
+
+
+def bump_for_branch(branch: str) -> str:
+    """trunk-semver's branch rule, for runs without it: feature/* and feat/* are minor, the rest patch."""
+    return "minor" if branch.startswith(("feature/", "feat/")) else "patch"

verbump_cli-1.0.0.dist-info/METADATA

@@ -0,0 +1,312 @@
+Metadata-Version: 2.4
+Name: verbump-cli
+Version: 1.0.0
+Summary: Version and changelog bumps for repos
+Author: Gonçalo Faria
+License-Expression: MIT
+Project-URL: Action, https://github.com/TheKathan/verbump-action
+Project-URL: Source, https://github.com/TheKathan/verbump
+Project-URL: Changelog, https://github.com/TheKathan/verbump/blob/main/CHANGELOG.md
+Keywords: version,semver,changelog,release,monorepo,bump,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<h1 align="center">verbump</h1>
+
+<p align="center">
+  <a href="https://github.com/TheKathan/verbump/actions/workflows/test.yml"><img alt="tests" src="https://github.com/TheKathan/verbump/actions/workflows/test.yml/badge.svg"></a>
+  <a href="https://pypi.org/project/verbump-cli/"><img alt="PyPI" src="https://img.shields.io/pypi/v/verbump-cli"></a>
+  <img alt="license" src="https://img.shields.io/github/license/TheKathan/verbump">
+  <img alt="Python 3.11+" src="https://img.shields.io/badge/python-%E2%89%A5%203.11-3776AB">
+  <img alt="dependencies: none" src="https://img.shields.io/badge/dependencies-none-brightgreen">
+</p>
+
+**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`
+
+<p align="center"><img alt="verbump in a repo with two packages. verbump status shows api at 1.4.0 with 0 changed files and web at 0.3.0 with 2 changed files. git log shows a commit feat(web): checkout page that touched apps/web. verbump apply --branch feat/checkout prints web: 0.3.0 -> 0.4.0 (minor, tag web/v0.4.0) and writes apps/web/package.json and apps/web/CHANGELOG.md. git diff shows the version going from 0.3.0 to 0.4.0, and verbump notes web prints the release notes: Added, Checkout page." src="https://raw.githubusercontent.com/TheKathan/verbump/main/assets/demo.gif" width="800"><br><sub>A PR from <code>feat/checkout</code> changed only <code>apps/web</code>: web gets a minor bump and its release notes, api stays at 1.4.0.</sub></p>
+
+## Try it in 60 seconds
+
+With verbump [installed](#quick-start), this builds the repo from the recording in a scratch folder and releases it:
+
+```bash
+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](https://github.com/TheKathan/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
+
+| Use | What you get |
+|---|---|
+| **A repo with several services or libraries** | Per-package versions, tags (`api/v1.5.0`) and changelogs, from one config. [Example](https://github.com/TheKathan/verbump/blob/main/examples/monorepo/verbump.toml) |
+| **A single package** | `tag_format = "v{version}"` and one package at `.`; verbump releases itself this way. [Its config](https://github.com/TheKathan/verbump/blob/main/verbump.toml) |
+| **GitHub Actions** | [verbump-action](https://github.com/TheKathan/verbump-action) bumps, commits, tags, pushes and publishes a GitHub release per package, on any stack. |
+| **Any other CI** | Four commands: `apply`, `check`, `tag`, `notes`. [Recipe](#using-it-in-ci) |
+
+## 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`.
+
+```bash
+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:
+
+```toml
+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`:
+
+```console
+$ 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.
+
+```console
+$ 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](#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.
+
+```toml
+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.
+
+| Key | Where | Default | Meaning |
+|---|---|---|---|
+| `tag_format` | top level, package | `{name}/v{version}` | Tag name. Uses `{name}`, `{path}` and `{version}`; `{version}` appears exactly once. `{path}` can't be used at the repo root. Two packages can't share a tag. |
+| `changelog` | top level, package | `CHANGELOG.md` | Changelog file, relative to the package `path`. `""` turns it off. |
+| `major_tag` | top level, package | `false` | Also move a major tag, such as `api/v1`, on each release. |
+| `commit_message` | top level | `chore(release): {releases}` | Commit message in the plan. `{releases}` becomes `api 1.5.0, web 0.3.1`. |
+| `path` | package | `.` | The package folder, relative to the repo root. It must stay inside the repo. |
+| `files` | package | none | Files that carry the version, relative to `path`. See [Supported files](#supported-files). |
+| `watch` | package | none | Other repo paths whose changes also release this package. |
+| `exclude` | package | none | Glob patterns. Changes only to matching files don't release the package. Patterns match the repo path or the path relative to the package. |
+| `initial_version` | package | `0.0.0` | Where a package with no tag and no version files starts. |
+
+For a single-package repo, use `tag_format = "v{version}"` and one package at `path = "."`. This repo's own [`verbump.toml`](https://github.com/TheKathan/verbump/blob/main/verbump.toml) is an example. [`examples/monorepo/verbump.toml`](https://github.com/TheKathan/verbump/blob/main/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:
+
+```toml
+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
+]
+```
+
+| Key | Meaning |
+|---|---|
+| `path` | The file, relative to the package `path`. Required. |
+| `kind` | A built-in matcher: `json`, `toml`, `yaml`, `helm`, `plain`, `python`, `msbuild`, `assemblyinfo`, `maven`, `properties`, `gradle`, `ruby`, `elixir` or `dockerfile`. |
+| `pattern` | Your own regex. It needs a `(?P<version>...)` group. It wins over `kind`. |
+| `after` | Search only after the first occurrence of this text. |
+| `replace_all` | Rewrite every match. By default only the first match is rewritten, and when there are several matches the first is read. |
+
+## 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`.
+
+| Stack | Files | Matches |
+|---|---|---|
+| Node, PHP, Deno | `package.json`, `composer.json`, `deno.json`, `jsr.json`, `manifest.json` | `"version": "X.Y.Z"` |
+| Python | `pyproject.toml` | `version = "X.Y.Z"` at the start of a line |
+| Python | `setup.cfg` | `version = X.Y.Z` |
+| Python | `*.py` | `__version__ = "X.Y.Z"` |
+| Rust | `Cargo.toml` | `version = "X.Y.Z"` at the start of a line |
+| .NET | `*.csproj`, `*.fsproj`, `*.vbproj`, `*.props` | `<Version>` or `<VersionPrefix>` |
+| .NET | `AssemblyInfo.cs` | every `Assembly[File\|Informational]Version("X.Y.Z...")` |
+| Java, Kotlin | `pom.xml` | the project's `<version>`, after `</parent>` when there is one |
+| Java, Kotlin | `build.gradle`, `build.gradle.kts` | `version = "X.Y.Z"` or `version 'X.Y.Z'` |
+| Java, Kotlin | `gradle.properties` | `version=X.Y.Z` |
+| Ruby | `version.rb`, `*.gemspec` | `VERSION = "X.Y.Z"`, `.version = "X.Y.Z"` |
+| Elixir | `mix.exs` | `version: "X.Y.Z"` |
+| Dart, Flutter | `pubspec.yaml` | `version: X.Y.Z` (a `+build` suffix is kept) |
+| Helm | `Chart.yaml` | `version: X.Y.Z`. Set `kind = "helm"` to move `appVersion` too. |
+| Docker | `Dockerfile` | `LABEL ... version="X.Y.Z"` |
+| Any | `VERSION`, `VERSION.txt`, `version.txt`, `.version` | the whole file |
+| Go, Swift, ... | no file | the version lives only in the tags; use `tag_format = "{path}/v{version}"` for Go modules |
+
+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>
+```
+
+| Command | What it does |
+|---|---|
+| `status [--json]` | Lists each package with its file version, last tag and number of changed files. |
+| `plan [options]` | Shows what would release. Changes nothing. |
+| `apply [options] [--date YYYY-MM-DD]` | Writes versions and changelogs, and prints the plan. Doesn't commit or tag. `--date` defaults to today, UTC. |
+| `tag --plan FILE` | Creates the annotated tags in a saved plan, and moves its major tags. Doesn't push. |
+| `notes <package> [<version>]` | Prints a version's changelog section, for a release body. Without a version, it uses the package's file version. |
+| `set <package> <version> [--date D]` | Writes an exact version into one package's files and changelog. |
+| `check` | Prints each package's file version. Exits 1 if a package's version files disagree. |
+| `init` | Writes a starter `verbump.toml`. It won't overwrite an existing one. |
+| `demo [--dir D] [--setup-only]` | A narrated release in a throwaway repo with a Python and a Node package. `--dir` keeps the repo; `--setup-only` only builds it and prints its path. |
+
+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`
+
+| Option | Meaning |
+|---|---|
+| `--exact NAME=X.Y.Z` | Release a package at exactly this version, changed or not. Repeatable. |
+| `--release-branch <branch>` | If the branch is `release/<package>/X.Y.Z` (or `release/X.Y.Z` with one package), it sets `--exact`. Other branches are ignored. |
+| `--only NAME` | Limit the run to this package. Repeatable. |
+| `--json` | Print the plan as JSON instead of text. |
+| `--plan-out FILE` | Also write the plan as JSON to this file. |
+
+### 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, use [TheKathan/verbump-action](https://github.com/TheKathan/verbump-action). It installs `verbump-cli` from PyPI, then:
+
+1. applies the bump;
+2. commits, tags and pushes;
+3. publishes a GitHub release per package.
+
+It takes the bump as an input, from any source (trunk-semver, a branch name 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:
+
+```bash
+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`](https://github.com/TheKathan/verbump/blob/main/.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](https://github.com/TheKathan/verbump/issues), and pull requests are welcome: see [CONTRIBUTING](https://github.com/TheKathan/verbump/blob/main/CONTRIBUTING.md) and the [code of conduct](https://github.com/TheKathan/verbump/blob/main/CODE_OF_CONDUCT.md). Issues about the GitHub Action go to [verbump-action](https://github.com/TheKathan/verbump-action/issues). If verbump saves you a release chore, a star helps others find it.
+
+[CHANGELOG](https://github.com/TheKathan/verbump/blob/main/CHANGELOG.md) · [SECURITY](https://github.com/TheKathan/verbump/blob/main/SECURITY.md) · [Publishing](https://github.com/TheKathan/verbump/blob/main/docs/publishing.md) · [LICENSE](https://github.com/TheKathan/verbump/blob/main/LICENSE) (MIT)

verbump_cli-1.0.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+verbump/__init__.py,sha256=KWGbh9aCZAJ5WO-xrOpmbw2EDpd67XRM7FcEjzbUCP4,77
+verbump/__main__.py,sha256=-OcM1HV8tbqNJ_49S-4W2j8oWSl-4KHfLf245qcMNDc,37
+verbump/changelog.py,sha256=3JzDgwWU_ov7S0S-E43vK-PVdGbV9IdQESRqv4XiTtU,2198
+verbump/cli.py,sha256=UKzIAF6i0g8XhqD_PsUG0ye5F_AuwR2dUx2teGyV0ow,9447
+verbump/config.py,sha256=jp1sauUVEIDHqgFAPhyc_DzDBtOoeXGnZaRqYdClga4,6188
+verbump/demo.py,sha256=mVtffql3OIcztqjz0Z3d5IE6ekukItOI9UQLHTv17Jw,4063
+verbump/files.py,sha256=-H4G9J6Cgpef5OouVRdBeGlTvOIQrEgDVCuPGmy70Po,5079
+verbump/gitutil.py,sha256=T8Nl4pyWO48fq851DyEVyIbDJ_-4xdlSAbtHjEEYrWA,1427
+verbump/release.py,sha256=3OG3a8KFoCDA-yL3668v45i9f0UgMsSh9iMJzFqqL4Y,5507
+verbump/semver.py,sha256=p6JgYbqcHdSMdsb27WkyF3FwJgk3x8jTItEMgkOBY7Q,1479
+verbump_cli-1.0.0.dist-info/licenses/LICENSE,sha256=7xfhHrWbWZP8d3mzgR332iKkKjx0_JOzCbXZx5cjtkk,1071
+verbump_cli-1.0.0.dist-info/METADATA,sha256=ooBaR5v4_tFoH6GFPFuSSUjCBXLhPaxKzyb7S6XoiaQ,19269
+verbump_cli-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+verbump_cli-1.0.0.dist-info/entry_points.txt,sha256=A8NC1mSekstNNkMKgLNn11Fmwn2D-y-iO77v20A3Mpk,45
+verbump_cli-1.0.0.dist-info/top_level.txt,sha256=7XJfWZOANycbCanXmw3iyGKSuzAF6dQltLoX2GHZc6U,8
+verbump_cli-1.0.0.dist-info/RECORD,,

verbump_cli-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

verbump_cli-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+verbump = verbump.cli:main

verbump_cli-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gonçalo Faria
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

verbump_cli-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+verbump