Select a numeric release tag

tags calculates a version from pending changelog fragments and existing tags. It also checks a proposed version and finds the tag for the GitHub comparison link. It reads tag names from standard input and never creates or moves a tag.

Calculate the next version

Use --next auto in a release workflow. --directory defaults to changelog.d:

git tag --list | uvx --from release-creator release-creator tags --next auto

An *.breaking.md fragment requests a major bump. Otherwise, an *.feature.md fragment requests a minor bump; other fragments request a patch bump. If several kinds are present, the largest bump wins. From 1.2.3, a feature produces 1.3.0 and a bug fix alone produces 1.2.4. With no numeric tags, a feature produces 0.1.0.

For repositories with v-prefixed release tags, add --prefix v. Existing v1.2.3 and 1.2.3 tags both count when selecting the next version; the option controls the new tag’s spelling:

git tag --list | uvx --from release-creator release-creator tags --next auto --prefix v

In a repository that tags several packages, pass --package and the complete tag list. The command selects only that package’s tags, reads fragments from changelog.d/<package> by default, and prints the full package tag:

git tag --list | release-creator tags --next auto --package pyproject-fmt

With pyproject-fmt/2.30.3 already tagged and a pending bug fix, this prints pyproject-fmt/2.30.4. Other packages’ tags do not affect the version.

For tox-dev libraries, both adding and dropping a supported Python version use a feature fragment, such as +drop-python-3-9.feature.md. The note appears under Added and automatic version selection makes a minor release. New releases will not install on a dropped Python version. Users who need that version can install an older release. State the exact Python version in the fragment. Reserve *.breaking.md for changes that require a major bump.

Choose --next major, minor, or patch to override that classification. --next calver uses year.month.patch: the first October 2026 release is 2026.10.0, and the next is 2026.10.1. CalVer uses the runner’s current date. Every choice requires at least one fragment and must produce a version newer than all existing numeric tags.

Check a proposed version

Suppose git tag --list prints 1.2.1, 1.2.2, and docs-preview. Before preparing 1.2.3, run:

git tag --list | uvx --from release-creator release-creator tags 1.2.3 --require-newer

A successful check prints nothing and exits with status zero. If 1.2.3, v1.2.3, or a newer numeric tag already exists, the command fails. This prevents release preparation from reusing a version or publishing an older one. Prerelease, postrelease, and development suffixes are accepted on tags with three numeric components. For example, 1.2.3 is newer than 1.2.3rc1.

Find the comparison base

For the same tag list, run:

git tag --list | uvx --from release-creator release-creator tags 1.2.3 --previous

The output is 1.2.2. Pass it to notes --previous 1.2.2 to link the changes since that release. For a first numeric release, --previous prints nothing; notes then links to the commits at the new tag.

For package tags, add --package pyproject-fmt and pass either 2.30.4 or pyproject-fmt/2.30.4 as the target. The output keeps the package prefix, for example pyproject-fmt/2.30.3, ready for notes --previous. The same scope applies to --require-newer.

Rules and failure cases

The proposed tag must have three numeric components, major.minor.patch or year.month.patch, with an optional v prefix. Existing tags with other forms, such as docs-preview or a floating v1 tag, do not take part in the comparison. Numeric components are compared as numbers, so v1.2.10 follows 1.2.9. --previous selects the greatest numeric tag below the proposed one, retains its prefix, and ignores input order.

Without --previous or --require-newer, the command only validates the proposed tag’s format and does not read standard input. Choose one option at a time; they answer different questions.