Usage¶

clk¶

$ clk <options> <subcommand> ...

A helper for maintaining changelog files that use keep-a-changelog format.

Subcommands

check: Check contents of the changelog file.
fix: Fix contents of the changelog file.
bump: Move entries from unreleased to a new release.
find: Find a changelog entry for a given release version.
check-tag: Check if a git tag conforms to the versioning specification.

Options

-c, --config {<*.toml>|<*.yaml>|<*.yml>}¶

Override path to the config file.

By default, Changelog Keeper searches for .cl-keeper.yaml, .cl-keeper.toml, or pyproject.toml in the current directory or its parents.

If --input is given, Changelog Keeper searches for config starting from the input file’s directory instead.

If config can’t be found, Changelog Keeper will use the default config.

-i, --input {-|<path>}¶

Override path to the changelog file. Pass - to read file from stdin.

By default, Changelog Keeper searches for config, then searches for CHANGELOG.md relative to the config file’s directory.

If config can’t be found, Changelog Keeper searches for CHANGELOG.md in the current directory instead.

--strict¶: Increase severity of all messages by one level.

-m, --machine-readable-diagnostics¶: Print diagnostics in a machine readable format: file:line:severity:code:message.

Global config overrides

--cfg-*¶: See config documentation for details, or run clk --help=all to list all flags.

Misc options

-h, --help¶: Print this message and exit.

-V, --version¶: Print program version and exit.

-v, --verbose...¶: Increase output verbosity.

--bug-report¶: Print environment data for bug report and exit.

--completions [<shell>]¶

Install or update autocompletion scripts and exit.

Supported shells: all, uninstall, bash, zsh, fish, or pwsh.

--color, --no-color¶

Enable or disable ANSI colors.

Aliases:: --color={true|false|ansi|ansi-256|ansi-true}

clk check¶

$ clk check <options>

Check contents of the changelog file.

clk fix¶

$ clk fix <options> [--dry-run] [--diff]

Fix contents of the changelog file.

Options

--dry-run¶: Don’t save changes, print the diff instead. Implies --diff.

--diff¶: Print diff to stdout.

clk bump¶

$ clk bump <options> [--ignore-errors] [--dry-run] [--edit] <version>
$ clk bump <options> [--ignore-errors] [--dry-run] [--edit] [auto|major|minor|patch|post] [--alpha|--beta|--rc]

Move entries from unreleased to a new release.

First form moves entries from the unreleased section to a new release for the specific version.

Second form does the same, but the new version number is generated based on the last release.

Arguments

<version>¶

Release version or tag that will be used for a new release. Can start with tag_prefix, in which case the prefix is stripped.

If <version> is major, minor, patch, or post, this command bumps the corresponding component of the latest version. In this case, the latest version is determined by comparing all releases (and tags, if check_repo_tags is true) with respect to the chosen version_format.

If <version> is auto, this command inspects contents of the unreleased section to determine which version component to bump:

if there is a breaking category, it creates a major release;
if there are added, changed, or removed categories, it creates a minor release;
if there are security, deprecated, performance, or fixed categories, it creates a patch release;
if none of the above categories are present, the command fails.

The list of categories for automatic bumping can be adjusted, see config options bump_patch_categories, bump_minor_categories, bump_major_categories.

Options

--alpha¶

Create an alpha pre-release.

This option is only allowed if <version> is auto, major, minor, patch, or post, or if <version> is not given at all. In the later case, the previous release should itself be a pre-release.

--beta¶: Create a beta pre-release, similar to --alpha.

--rc¶

Create a release candidate, similar to --alpha.

Aliases:: --pre

--ignore-errors¶: Produce result even if errors are detected.

--dry-run¶: Don’t save changes, print the diff instead. Implies --diff.

--diff¶: Print diff to stdout.

--edit¶: Open generated changes for editing.

--commit¶

Commit and tag the release after updating changelog.

Changelog Keeper will pause before committing and allow you to inspect repository or cancel the commit.

Examples

Specifying version manually

You can always supply a specific version for a new release. As long as there are no prior releases with the same version, this operation will succeed:

clk bump 1.0.5

Automatic version detection

Changelog keeper can suggest next version based on changelog content (the --dry-run flag is handy here):

clk bump auto

Bumping a version component

you can bump a version component by setting <version> to major, minor, patch, or post:

clk bump minor  # 1.0.0 -> 1.1.0

Pre-releases

You can make a pre-release by adding --alpha, --beta, or --rc:

clk bump major --beta  # 1.5.1 -> 2.0.0b0

If the last release is a pre-release itself, you can bump its pre-release version component:

clk bump --beta  # 1.0.0b0 -> 1.0.0b1
clk bump --rc  # 1.0.0b0 -> 1.0.0rc0

clk find¶

$ clk find <options> [--ignore-errors] [--json] <version>
$ clk find <options> [--ignore-errors] [--json] unreleased
$ clk find <options> [--ignore-errors] [--json] latest

Find a changelog entry for a given release version.

First form prints a changelog entry for the given release version.

Second form prints contents of the unreleased section.

Third form scans the changelog file and prints contents of the top-most non-unreleased entry. This form is intended for situations when version_format is none, i.e. there is no way to canonize version number.

If errors detected in the changelog, the command fails unless --ignore-errors was given.

If changelog entry isn’t found, the requested version is searched in the repo tags. If it’s found in the repo, and it satisfies config options ignore_missing_releases_before or ignore_missing_releases_regexp, an empty result is printed.

Arguments

<version>¶: Version that will be extracted from the changelog. Can start with tag_prefix, in which case the prefix is stripped.

Options

--ignore-errors¶: Produce result even if errors are detected.

--json¶: Print data in JSON format.

-o, --output {-|<path>}¶

Where to write results. Pass - to write to stdout.

Default:: -

Examples

Find an exact version:

clk find v1.0.0-rc2

Find the first version (barring the unreleased section) that appears in the changelog:

clk find latest

Find the unreleased section:

clk find unreleased

Json output

If --json flag is given, a JSON object is printed to stdout. It will contain the following fields:

version

Version string, as appears in the changelog.

Can be null if unreleased section is requested.

canonizedVersion

Version string, canonized according to the used version_format.

If version_format is null or canonization fails, this will contain string from version.

tag

Tag that corresponds to this version.

Can be null if requested release not found, if unreleased section is requested, if check_repo_tags is false, if version canonization fails, or if tag is not found for this release.

text

Text extracted from the changelog entry.

Can be empty if requested release not found.

isLatestInChangelog

true if found version appears first in the changelog file.

Can be null if requested release not found, or if unreleased section is requested.

isLatestInSemanticOrder

true if this is the latest known release.

Release versions are compared with respect to the selected version_format. If check_repo_tags is true, this flag also checks all tags found in the repository.

Can be null if requested release not found, or if unreleased section is requested.

isLatest

Equals to isLatestInSemanticOrder if it’s not null, otherwise equals to isLatestInChangelog.

isPreRelease

true if release version contains a pre-release component, like beta or rc.

Can be null if requested release not found, if unreleased section is requested, or if version canonization fails.

isPostRelease

true if release version contains a post-release component.

Can be null if requested release not found, if unreleased section is requested, or if version canonization fails.

isUnreleased

true if unreleased section is requested.

clk check-tag¶

$ clk check-tag <options> <tag>

Check if a git tag conforms to the versioning specification.

This command is handy to use in release CI or in a pre-push git hook to verify that all tags conform to the selected versioning specification.

Arguments

<tag>¶: Full name of the tag to check.