kc

kc is a CLI utility that interfaces with changelogs that follow the Keep a Changelog format.

At a glance, kc can

• generate changelogs,
• generate, list, edit and delete releases,
• generate release and @mention links,
• sort releases,
• create and group changes,
• stash unreleased changes, and
• more...

For an example changelog, see that of Keep a Changelog.

Installation

kc may be installed by

• downloading a release package for your platform, unpacking it and placing the pre-compiled binary in your $PATH, or
• issuing go install github.com/xuoe/kc@latest, or
• building it from source, which has the benefit of also installing the manual page.

Usage

This section serves as a quick guide to using kc. For more details, see the Getting Help section.

Initialization

For most invocations, kc requires a changelog file (usually CHANGELOG.md) to be present either in the current directory or up the directory tree. If a changelog does not already exist, you can initialize one by issuing kc --init [changelog]. (See kc --print changelog.templates for a list of changelog templates.)

You may also require a configuration file to alter the link generation process or which change labels are allowed. Run kc --init co[nfig] and choose a configuration template. This will create a .kcrc file in the current directory. Otherwise, without a configuration file, no links are generated beyond those already found in the changelog file.

Adding Changes

kc operates around changes and releases. To introduce a change, invoke kc [LABEL] [TEXT]. If you omit TEXT, kc will open a text editor (see the manual for Environment) to capture the change text. If you also omit LABEL, kc will either treat it as TEXT or inform you that a label is required. (See kc --print config.labels for a list of change labels.)

Prior to release, all changes are stashed under an Unreleased section.

Releasing Changes

To release changes stashed under the Unreleased section, issue kc --release [VERSION]. For example, to increment the minor version number, issue kc --release minor. This moves the unreleased changes into a new release section, whose title contains the incremented version string (as per semver) and the current date in ISO-8601 format. At this point, running kc --list prints a single line: 0.1.0.

Editing a Release

To edit the latest release, issue kc --edit. This opens a text editor with the release body ready for editing. You can edit any of the following: the version string, the release date, any change label and any change text. Once done, save the file and exit the editor.

Note that if the Unreleased section exists, it will be opened for editing instead.

Inspecting a Release

To see changes introduced by the latest release, invoke kc --show without any arguments.

Note that if the Unreleased section exists, it will be printed instead.

Deleting a Release

To delete the latest release, issue kc --delete without any arguments. Given the example in Releasing Changes, running kc --list now prints nothing.

Note that if changes have been added since the latest release, this deletes the implicit Unreleased section instead.

Getting Help

kc --help provides a quick overview of the available commands and their arguments. For a more in-depth coverage, consult the manual distributed with the release package, or the one generated during the build process (man 1 kc).

License

kc is released under the MIT license.