This tool contains utilities to handle your changelogs for the better. Its linter can be used to enforce a standard for your changelogs and the CLI can be used to add, update or delete entries.

It was designed to be used as a constant companion for all of your projects. When creating a new project, clu init shall be the second thing to execute - right after git init.

To install the application from source, run

cargo install --git https://github.com/MalteHerrmann/changelog-utils

The application is also available to be used with a Docker image. It can be built locally by executing make docker-build or downloaded from the GitHub container registry by running

docker pull ghcr.io/malteherrmann/changelog-utils:[TAG]

The available subcommands can be listed when running clu help:

Usage: clu <COMMAND>

Commands:
  add      Adds a new entry to the unreleased section of the changelog
  fix      Applies all possible auto-fixes to the changelog
  lint     Checks if the changelog contents adhere to the defined rules
  init     Initializes the changelog configuration in the current directory
  config   Adjust the changelog configuration like allowed categories, change types or other
  release  Turns the Unreleased section into a new release with the given version
  help     Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

This application is designed to be one of the first things you use within your projects' folder - right after creating the folder and running git init. By executing clu init, an empty skeleton for the changelog is generated (CHANGELOG.md) as well as a default configuration (.clconfig.json).

Note, that a pre-exixisting changelog will not be overwritten, so you can also run this command in existing projects. In that case, it will only create the default configuration.

You can add or remove configurations as you like with the corresponding subcommands of clu config.

Usage: clu config <COMMAND>

Commands:
  category        Adjust the allowed categories for changelog entries
  change-type     Adjust the allowed change types within releases (like 'Bug Fixes', 'Features', etc.)
  legacy-version  Set or unset the optional legacy version
  show            Shows the current configuration
  spelling        Adjust the expected spellings that should be enforced in the changelog
  target-repo     Sets the target repository for the changelog entries
  help            Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

The linter can be escaped for a given line or just for specific sublinters. To keep a consistent changelog structure we only allow for escapes to be effective for individual PR changes instead of release (e.g. ## [v0.1.0](...)) or change type lines (e.g. ### Bug Fixes).

The following escape patterns are available:

All available escape patterns can be appended by an optional description that is separated by a colon, e.g. <!-- clu-disable-next-line-duplicate-pr: known duplicate (backported PR) -->.

Authenticated GitHub requests are made if an environment variable GITHUB_TOKEN is found. This is required to check for available open pull requests of the current branch in private repositories.

NOTE: The GitHub authentication is only used for read access of open PRs.