Config¶

Changelog Keeper searches for .cl-keeper.yaml, .cl-keeper.toml, or pyproject.toml. In pyproject.toml, keeper’s config is located under the tool.cl_keeper key.

Examples¶

Basic python config¶

.cl-keeper.yaml

# Default is `semver`; there's also `python` and `python-strict`.
version_format: python-semver

# Prefix for your git tags. Default is `v`.
tag_prefix: ""

pyproject.toml

[tool.cl_keeper]

# Default is `python`; there's also `python-strict`.
version_format = "python-semver"

# Prefix for your git tags. Default is `v`.
tag_prefix = ""

Example changelog

# Changelog

## v1.5.1 - 2025-05-01

### Added

- Added some feature.

Custom titles and decorations for change categories¶

.cl-keeper.yaml

change_categories:
  breaking: "💥 Breaking"
  security: "🔒 Security"
  added: "✨ Added"
  changed: "🔧 Changed"
  deprecated: "⚠️ Deprecated"
  removed: "🗑️ Removed"
  performance: "⚡ Performance"
  fixed: "🐛 Fixed"
release_date_decorations: [" (", ")"]
version_decorations: ["v", ""]

Example changelog

# Changelog

## v1.5.1 (2025-05-01)

### ✨ Added

- Added some feature.

Using item categories instead of sub-sections¶

.cl-keeper.yaml

# Disable change categories.
change_categories: {}

# Enable defaults for item categories.
use_default_item_categories: true

Example changelog

# Changelog

## v1.5.1 - 2025-05-01

- [added] Added some feature.
- [removed] Removed a deprecated feature.

Custom sub-sections with item categories¶

.cl-keeper.yaml

# Set custom categories.
change_categories:
  frontend: Frontend
  api: Api
# Enable defaults for item categories.
use_default_item_categories: true
# Set custom prefixes for item categories.
item_categories:
  breaking: "💥 "
  security: "🔒 "
  added: "✨ "
  changed: "🔧 "
  deprecated: "⚠️ "
  removed: "🗑️ "
  performance: "⚡ "
  fixed: "🐛 "

Example changelog

# Changelog

## v1.5.1 - 2025-05-01

### Frontend

- ✨ Added some feature.

### Api

- 🗑️ Removed deprecated interfaces.

Full list of config keys¶

config .cl-keeper.yaml¶

file: string = "CHANGELOG.md"¶: Path to the changelog file, relative to this config location.

format_wrapping: integer | Wrapping = 90¶

Max line width for wrapping markdown files.

Can be a positive number, a string no, or a string keep. no will format all paragraphs in a single line, while keep will preserve the original wrapping.

Flags:: --cfg-format-wrapping {<int>|no|keep}

change_categories: {[string]: string} = {"breaking": "Breaking", "security": "Security", "added": "Added", "changed": "Changed", "deprecated": "Deprecated", "removed": "Removed", "performance": "Performance", "fixed": "Fixed"}¶

Ordering and titles for change categories.

This config item defines known change categories (i.e. third level headings in release section, such as “Added” or “Changed”).

Its keys are category names used in other config items to refer to sections.

Its values are category titles that will be used in section headings. If a value is empty, section’s heading will not be replaced.

Order of elements defines the preferred order of sections in the changelog.

By default, changelog keeper defines the following sections:

Category	Title
`breaking`	Breaking
`security`	Security
`added`	Added
`changed`	Changed
`deprecated`	Deprecated
`removed`	Removed
`performance`	Performance
`fixed`	Fixed

Meta value:: …
Flags:: --cfg-change-categories [<str>:<str> ...]
Aliases:: --cfg-change-categories='<str>:<str>[ <str>:<str>[ ...]]' – can be given as a single argument with delimiter-separated list.

extra_change_categories: {[string]: string} = {}¶

Additional items that will be added to change_categories without completely overriding it.

Flags:: --cfg-extra-change-categories [<str>:<str> ...]
Aliases:: --cfg-extra-change-categories='<str>:<str>[ <str>:<str>[ ...]]' – can be given as a single argument with delimiter-separated list.

change_categories_map: {[string]: string} = {}¶

A mapping from regular expressions to change category names, used to parse and normalize categories.

When processing a release, each third level heading will be matched against these regular expressions to figure out which section it represents. If there is a match, the heading content will be replaced by the one from change_categories, and the section will be reordered to match the order from change_categories.

Regular expression syntax is described in the re module documentation. Regular expressions will be compiled without flags, but you can use inline flags to enable case-insensitivity.

Meta value:: …
Flags:: --cfg-change-categories-map [<str>:<str> ...]
Aliases:: --cfg-change-categories-map='<str>:<str>[ <str>:<str>[ ...]]' – can be given as a single argument with delimiter-separated list.

extra_change_categories_map: {[string]: string} = {}¶

Additional items that will be added to change_categories_map without completely overriding it.

Flags:: --cfg-extra-change-categories-map [<str>:<str> ...]
Aliases:: --cfg-extra-change-categories-map='<str>:<str>[ <str>:<str>[ ...]]' – can be given as a single argument with delimiter-separated list.

use_default_item_categories: boolean = false¶

Add default lists for item_categories and item_categories_map.

Flags:

--cfg-use-default-item-categories

Aliases:

--cfg-no-use-default-item-categories
--cfg-use-default-item-categories={true|false}

item_categories: {[string]: string} = {}¶

Ordering and titles for individual changelog items.

If you want to detect categories of individual items and sort item lists inside of each change category, you can fill this config item. This is intended for situations when you want to group items by using prefixes instead of third-level headings.

Tip

Enable use_default_item_categories to enable defaults for item_categories and item_categories_map.

Flags:: --cfg-item-categories [<str>:<str> ...]
Aliases:: --cfg-item-categories='<str>:<str>[ <str>:<str>[ ...]]' – can be given as a single argument with delimiter-separated list.

extra_item_categories: {[string]: string} = {}¶

Additional items that will be added to item_categories without completely overriding it.

Flags:: --cfg-extra-item-categories [<str>:<str> ...]
Aliases:: --cfg-extra-item-categories='<str>:<str>[ <str>:<str>[ ...]]' – can be given as a single argument with delimiter-separated list.

item_categories_map: {[string]: string} = {}¶

A mapping from regular expressions to item category names, used to parse and normalize item categories.

See also

Enable use_default_item_categories to enable defaults for item_categories and item_categories_map.

Flags:: --cfg-item-categories-map [<str>:<str> ...]
Aliases:: --cfg-item-categories-map='<str>:<str>[ <str>:<str>[ ...]]' – can be given as a single argument with delimiter-separated list.

extra_item_categories_map: {[string]: string} = {}¶

Additional items that will be added to item_categories_map without completely overriding it.

Flags:: --cfg-extra-item-categories-map [<str>:<str> ...]
Aliases:: --cfg-extra-item-categories-map='<str>:<str>[ <str>:<str>[ ...]]' – can be given as a single argument with delimiter-separated list.

bump_patch_categories: string[] = ["performance", "security", "fixed", "deprecated"]¶

If these change categories appear in unreleased section, suggest bumping the patch version component.

Default is security, deprecated, performance, fixed.

Meta value:: …
Flags:: --cfg-bump-patch-categories [<str> ...]
Aliases:: --cfg-bump-patch-categories='<str>[ <str>[ ...]]' – can be given as a single argument with delimiter-separated list.

extra_bump_patch_categories: string[] = []¶

Additional items that will be added to bump_patch_categories without completely overriding it.

Flags:: --cfg-extra-bump-patch-categories [<str> ...]
Aliases:: --cfg-extra-bump-patch-categories='<str>[ <str>[ ...]]' – can be given as a single argument with delimiter-separated list.

bump_minor_categories: string[] = ["added", "changed", "removed"]¶

If these change categories appear in unreleased section, suggest bumping the minor version component.

Default is added, changed, removed.

Meta value:: …
Flags:: --cfg-bump-minor-categories [<str> ...]
Aliases:: --cfg-bump-minor-categories='<str>[ <str>[ ...]]' – can be given as a single argument with delimiter-separated list.

extra_bump_minor_categories: string[] = []¶

Additional items that will be added to bump_minor_categories without completely overriding it.

Flags:: --cfg-extra-bump-minor-categories [<str> ...]
Aliases:: --cfg-extra-bump-minor-categories='<str>[ <str>[ ...]]' – can be given as a single argument with delimiter-separated list.

bump_major_categories: string[] = ["breaking"]¶

If these change categories appear in unreleased section, suggest bumping the major version component.

Default is breaking.

Meta value:: …
Flags:: --cfg-bump-major-categories [<str> ...]
Aliases:: --cfg-bump-major-categories='<str>[ <str>[ ...]]' – can be given as a single argument with delimiter-separated list.

extra_bump_major_categories: string[] = []¶

Additional items that will be added to bump_major_categories without completely overriding it.

Flags:: --cfg-extra-bump-major-categories [<str> ...]
Aliases:: --cfg-extra-bump-major-categories='<str>[ <str>[ ...]]' – can be given as a single argument with delimiter-separated list.

unreleased_name: string = "Unreleased"¶

Title for the unreleased section of the changelog.

Flags:: --cfg-unreleased-name <str>

unreleased_decorations: [string, string] = ["", ""]¶

Symbols that will be added around unreleased_name, but won’t be turned into a link.

This value should be a tuple of two strings, first will be placed before the title, second will be placed after.

Flags:: --cfg-unreleased-decorations <str> <str>
Aliases:: --cfg-unreleased-decorations='<str> <str>' – can be given as a single argument with delimiter-separated list.

unreleased_pattern: string = "(?i)unreleased"¶

Regular expression used to detect sections with unreleased changes.

Flags:: --cfg-unreleased-pattern <str>

release_decorations: [string, string] = ["", ""]¶

Symbols that will be added around each release heading.

Flags:: --cfg-release-decorations <str> <str>
Aliases:: --cfg-release-decorations='<str> <str>' – can be given as a single argument with delimiter-separated list.

release_date_decorations: [string, string] = [" - ", ""]¶

Symbols that will be added around release date.

Flags:: --cfg-release-date-decorations <str> <str>
Aliases:: --cfg-release-date-decorations='<str> <str>' – can be given as a single argument with delimiter-separated list.

version_decorations: [string, string] = ["", ""]¶

Symbols that will be added around release version.

Flags:: --cfg-version-decorations <str> <str>
Aliases:: --cfg-version-decorations='<str> <str>' – can be given as a single argument with delimiter-separated list.

release_comment_decorations: [string, string] = [" - ", ""]¶

Symbols that will be added around release comments.

Flags:: --cfg-release-comment-decorations <str> <str>
Aliases:: --cfg-release-comment-decorations='<str> <str>' – can be given as a single argument with delimiter-separated list.

add_release_date: boolean = true¶

Whether changelog entries should have a release date in their headings.

Flags:

--cfg-no-add-release-date

Aliases:

--cfg-add-release-date
--cfg-add-release-date={true|false}

add_release_link: boolean = true¶

Whether changelog entries should have links to tags/diffs in their headings.

Flags:

--cfg-no-add-release-link

Aliases:

--cfg-add-release-link
--cfg-add-release-link={true|false}

release_link_preset: ReleaseLinkPreset | null = null¶

Preset for release link templates.

By default, a correct preset is inferred by inspecting repository’s remotes. If this process fails, you can configure a preset manually.

Flags:: --cfg-release-link-preset {github|gitlab|none}

release_link_template: string | null = null¶

Template for a release link, formatted using Python’s str.format() method. This setting overrides link from preset.

The following template variables are available, in addition to ones declared in release_link_template_vars:

tag: Git tag for the current release.
prev_tag: Git tag for the previous release.

Example:

release_link_template: "https://{host}/{repo}/compare/{prev_tag}...{tag}"
release_link_template_vars:
    host: "github.com"
    repo: "taminomara/cl-keeper"

Flags:: --cfg-release-link-template <str>

release_link_template_last: string | null = null¶

Template for a link for an unreleased entry, formatted using Python’s str.format() method. This setting overrides link from preset.

The following template variables are available, in addition to ones declared in release_link_template_vars:

prev_tag: Git tag for the latest release.

Example:

release_link_template_last: "https://{host}/{repo}/compare/{prev_tag}...HEAD"
release_link_template_vars:
    host: "github.com"
    repo: "taminomara/cl-keeper"

Flags:: --cfg-release-link-template-last <str>

release_link_template_first: string | null = null¶

Template for a link for the first release, formatted using Python’s str.format() method. This setting overrides link from preset.

The following template variables are available, in addition to ones declared in release_link_template_vars:

tag: Git tag for the current release.

Example:

release_link_template_first: "https://{host}/{repo}/releases/tag/{tag}"
release_link_template_vars:
    host: "github.com"
    repo: "taminomara/cl-keeper"

Flags:: --cfg-release-link-template-first <str>

release_link_template_vars: {[string]: string} | null = null¶

Additional variables that will be available in release link templates.

Flags:: --cfg-release-link-template-vars [<str>:<str> ...]
Aliases:: --cfg-release-link-template-vars='<str>:<str>[ <str>:<str>[ ...]]' – can be given as a single argument with delimiter-separated list.

check_repo_tags: boolean = true¶

Scan git repo and ensure that changelog doesn’t miss any release.

Default is true.

Flags:

--cfg-no-check-repo-tags

Aliases:

--cfg-check-repo-tags
--cfg-check-repo-tags={true|false}

tag_prefix: string = "v"¶

Prefix for release tags.

Only tags that start with this prefix are considered release tags.

Default is "v".

Flags:: --cfg-tag-prefix <str>

version_format: VersionFormat = "semver"¶

Versioning schema used to parse and sort tags and versions.

See VersionFormat for details.

Flags:: --cfg-version-format {semver|semver-strict|python|python-strict|python-semver|none}

ignore_missing_releases_before: string | null = null¶

Don’t complain about missing releases for tags before this one.

Flags:: --cfg-ignore-missing-releases-before <str>

Don’t complain about missing releases if version matches this regexp.

Default regexp searches for the following substrings: dev|b|beta|a|alpha|rc|post.

Flags:: --cfg-ignore-missing-releases-regexp <str>

severity: {[IssueCode]: IssueSeverity} = {}¶

A mapping from issue code to issue severity. Allows customizing and disabling certain checks.

Flags:: --cfg-severity [<code>:<severity> ...]
Aliases:: --cfg-severity='<code>:<severity>[ <code>:<severity>[ ...]]' – can be given as a single argument with delimiter-separated list.

auto_detect_maps: boolean = true¶

Automatically fill out change_categories_map and item_categories_map based on change_categories and item_categories.

Disabling this feature removes automatically generated items from change_categories_map and item_categories_map, giving you full control over which regular expressions are used to detect change and item categories.

Note that maps for default change and item categories are not removed, only ones for user-defined categories.

Flags:

--cfg-no-auto-detect-maps

Aliases:

--cfg-auto-detect-maps
--cfg-auto-detect-maps={true|false}

Link presets¶

enum ReleaseLinkPreset¶

github¶

Will link releases to tags on github.

To use this preset, add the repo template variable to release_link_template_vars. It should contain url of your repository.

If you’re using self-hosted GitHub, you can also add the host template variable.

Example configuration:

release_link_preset: github
release_link_template_vars:
    repo: "taminomara/cl-keeper"

gitlab¶

Will link releases to tags on gitlab.

To use this preset, add the repo template variable to release_link_template_vars. It should contain url of your repository.

If you’re using self-hosted GitLab, you can also add the host template variable.

Example configuration:

release_link_preset: gitlab
release_link_template_vars:
    repo: "taminomara/cl-keeper"

none¶: Will not generate links automatically.

Supported version formats¶

enum VersionFormat¶

Specification for versioning formats.

Different settings affect parsing versions and sorting changelog entries.

Syntax overview

Schema	Release	Pre-release	Post-release	Post-release of a pre-release
`semver`	`1.0.0`	`1.0.0-b`, `1.0.0-b0`, `1.0.0-beta0`, etc.	not supported	not supported
`semver-strict`	`1.0.0`	`1.0.0-beta0`	not supported	not supported
`python`	`1.0.0`	`1.0.0b0`, `1.0.0-beta.0`, etc.	`1.0.0post0`, `1.0.0-rev.0`, etc.	`1.0.0b1.post2`, `1.0.0-beta.1post2`, etc.
`python-strict`	`1.0.0`	`1.0.0b0`	`1.0.0post0`	`1.0.0b0.post0`
`python-semver`	`1.0.0`	`1.0.0-beta0`	`1.0.0-post0`	`1.0.0-beta0.post0`

semver¶: Semantic versioning, as per semver 2.0 specification.

semver-strict¶

Semantic versioning with stricter constraints.

Versions must contain exactly three components (i.e. 1.0 is not valid, 1.0.0 is valid.) Only alpha, beta, and rc keywords followed by a number are allowed in pre-release section.

This schema ensures that all versions and tags are normalized and can be checked for equality without parsing them.

python¶: Python versioning specification, as per PyPA specification.

python-strict¶

Python versioning specification with stricter constraints.

Versions must contain exactly three components (i.e. 1.0 is not valid, 1.0.0 is valid.) Leading zeroes are not allowed. Pre- release part must not be separated by point or dash, and only a, b, rc or post keywords are allowed.

This schema ensures that all versions and tags are normalized and can be checked for equality without parsing them.

python-semver¶

Python versioning specification using semver-strict syntax.

This schema ensures that that all versions and tags are normalized, and other tools that rely on semver specification can work with them.

Note

Semver 2.0 doesn’t specify post-release semantics. As such, we use Python’s semantics and syntax: 1.0.0-post0, 1.0.0-rc1.post2, etc.

This tool will sort post-releases after actual releases, while other tools might not work this way.

none¶

No versioning semantics are implied.

Automatic sorting of releases is disabled. Canonization of versions when searching for release of merging duplicate releases is also disabled.

List of issue codes¶

enum IssueCode¶

GeneralFormattingError¶: A formatting error related to the general structure of the changelog.

InvalidVersion¶: Release version doesn’t follow the requested specification.

InvalidTag¶

Tag format doesn’t follow the requested versioning specification.

To disable all repository checks, set check_repo_tags to False.

MissingReleaseForTag¶

Found a tag that has no associated release.

To suppress this error for all versions before the given one, set ignore_missing_releases_before. To disable all repository checks, set check_repo_tags to False.

MissingTagForRelease¶

Found a release that has no associated tag in the repository.

To disable all repository checks, set check_repo_tags to False.

ReleaseOrdering¶

Releases are not ordered according to their versions.

Releases are compared according to the chosen versioning specification.

UnreleasedHeadingFormat¶

Heading for unreleased changes doesn’t meet formatting requirements.

Heading format is controlled by unreleased_name.

ReleaseHeadingFormat¶: Heading for a release doesn’t meet formatting requirements.

InvalidReleaseDate¶

Release date can’t be parsed.

This usually indicates that the release date is incorrect. For example, it refers to a day that doesn’t exist in the calendar.

MissingReleaseDate¶

Release date is missing.

add_release_date is True, but release date is missing.

UnexpectedReleaseDate¶

Release date should not be present.

add_release_date is False, but release date is present.

MissingReleaseLink¶

Release link is missing.

add_release_link is True, but release link is missing.

UnexpectedReleaseLink¶

Release link should not be present.

add_release_link is False, but release link is present.

IncorrectReleaseDate¶

Release date doesn’t match date of the release commit.

To disable all repository checks, set check_repo_tags to False.

IncorrectReleaseLink¶

Release link is incorrect.

Release links are generated using release_link_preset and release_link_template. We use order of releases from the changelog to generate links for commit ranges.

DuplicateReleases¶: Found multiple releases for the same version.

EmptyRelease¶

Section for a release is empty.

To ignore empty sections prior to some version, set ignore_missing_releases_before.

ReleaseHasNoChangeCategories¶

There are no change categories in a release.

To ignore releases without change items prior to some version, set ignore_missing_releases_before.

ChangeCategoryOrdering¶: Order of sub-sections within a release doesn’t match the one given in change_categories.

ChangeCategoryHeadingFormat¶: Heading for a change category doesn’t meet formatting requirements.

ChangeCategoryHasNoChangeLists¶

Change category contains no change lists.

item_categories is not empty, but there are no unordered lists in a change category that contain at least one item that matches an item category.

UnknownChangeCategory¶: Heading for a change category doesn’t appear in change_categories_map.

DuplicateChangeCategories¶: Found multiple release sub-sections with the same title.

EmptyChangeCategory¶: Found a release sub-section without content.

MultipleChangeLists¶

Found multiple change lists in the same change category.

This can happen due to improper formatting:

## v1.0.0

- [added] Feature.

Feature description is not properly indented.

- [added] Another feature.

ChangeListOrdering¶: Order of items within a change list doesn’t match the one given in item_categories.

ChangeListItemFormat¶: A change list item doesn’t start with a prefix defined in item_categories.

UnknownItemCategory¶: Can’t detect category for a change list item.

enum IssueSeverity¶

Severity of the issue.

error¶: Error.

warning¶: Warning.

weak-warning¶: Weak warning.

info¶: Info.

none¶: Not displayed.

Schema¶

If your IDE supports JSON schemas, config schema is available at https://cl-keeper.readthedocs.io/en/stable/schema.json.

For example, to enable schema in VSCode, add the following comment to your config:

# yaml-language-server: $schema=https://cl-keeper.readthedocs.io/en/stable/schema.json