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
create-pr Creates a PR in the configured target repository and adds the corresponding changelog entry
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:
Escape Pattern | Description |
---|---|
<!-- clu-disable-next-line --> |
Escapes any checks for the next line. |
<!-- clu-disable-next-line-duplicate-pr |
Escapes a potential duplicate PR warning in the next line. This applies especially for backported changes that occur in multiple releases. |
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.