MANUAL.adoc

kc(1)

Name

kc - a tool for managing changelogs

Synopsis

kc [OPTION]…​ COMMAND [ARGS]…​
kc [OPTION]…​ [LABEL] [TEXT]…​

Description

kc provides an interface for managing changelog files based on the "Keep a Changelog" format.

In addition to appending changes to a changelog, kc can create, edit, merge and delete releases. Depending on how it is configured, kc can generate links for @-style mentions and release links that point to the changes introduced by each release.

As specified in the Synopsis section, there are two modes of invoking kc:

• In the first form, kc executes a command on the current changelog file (see Files and Options). The commands are regular flags and are listed under the Commands section.

• In the second form, kc appends a change under the Unreleased section, which is auto-created if non-existent. LABEL specifies the label or category under which the change text must be included. TEXT is the actual change text, which, if omitted, instructs kc to open an editor (see Environment) to capture the change. If kc is configured to ignore change labels (see Configuration), LABEL becomes part of TEXT.

kc operates by stashing changes in an Unreleased section. When a new release is created, the stashed changes are moved into it and the Unreleased section is removed. At this point, adding a new change restarts the cycle.

Change text may span multiple lines and may be indented. However, kc discards any form of indentation and joins multiple lines by a double-space character sequence.

Releases (or the Unreleased section) may start with an introductory text, which can contain any text as long as it does not start with a release heading (##), change label heading (###), or change text (- …​). In those cases, prepending a space character to the text instructs kc to treat the special characters as plain text. Note that, besides manually editing the changelog file, the only way of adding a release note is by invoking --edit.

Options

-c, --changelog PATH

Load the changelog file found at PATH instead of searching for a changelog up the directory tree.

-C, --config PATH

Load the configuration file found at PATH instead of searching for a configuration file up the directory tree.

Commands

Commands are regular flags, except that only one command may be specified at a time and it should always follow any of the options defined in the Options section.

Most command arguments may be specified as case-insensitive prefixes.

-i, --init [FILE] [TEMPLATE]

Initialize a changelog or configuration file using TEMPLATE as the starting point. FILE may be one of config or changelog (default).

If TEMPLATE is omitted, kc attempts to use the default template for FILE.

If FILE is changelog and the option --changelog is provided, a changelog file is initialized at the specified path. The same applies for configuration files and --config.

Some templates may prompt the user for additional details (e.g., changelog title). To see the list of supported templates for FILE, issue kc --print FILE.templates.

-p, --print [PROP]…​

Print a kc property.

PROP keys may be separated by a space or dot character, i.e., changelog path and changelog.path are equivalent. If a key is specified as an asterisk (*), the entire key set at that depth level and below is printed, which differs from the empty string key where only the keys for the current property set are printed.

PROP keys may be specified as prefixes, e.g., ch f is equivalent to changelog file.

To see the entire property set, issue kc --print '*'; to see the top-level property set, drop the asterisk.

-s, --show [PATTERN]

Show releases that match PATTERN, or show the Unreleased section if PATTERN is omitted.

PATTERN is a prefix and/or a glob pattern that is matched against release version strings. Other commands that take a PATTERN expect the same format.

-d, --delete [PATTERN]

Delete releases that match PATTERN, or delete the Unreleased section if PATTERN is omitted.

-l, --list [PATTERN]

List release version strings that match PATTERN, or list all of them if PATTERN is omitted.

-L, --list-all [PATTERN]

Like --list, but also include the Unreleased section and the number of changes per release/section.

-e, --edit [PATTERN]

Edit releases that match PATTERN, or edit the Unreleased section if PATTERN is omitted. Editing is done by opening a text editor with the content (version, note and changes) of each matching release, one by one.

If the entire release body is deleted, saving the changes and exiting the editor deletes the release.

-r, --release [VERSION]

Release changes stashed under the Unreleased section.

VERSION may be one of:

major

Increment the major (#._._) number.

minor

Increment the minor (_.#._) number.

patch

Increment the patch (_._.#) number (default).

string

A version string that adheres to Semantic Versioning. If VERSION matches an existing release, kc attempts to merge the changes from the Unreleased section with the release specified by VERSION.

-R, --unrelease

Unrelease the changes introduced by the last release. Unreleasing consists of merging the last release with the Unreleased section. If no Unreleased section exists, the last release takes its place. In all cases, the link and date of the last release are discarded.

Release notes are joined by an empty line.

-t, --sort

Sort releases according to semver.

Configuration

kc may be configured through a TOML configuration file (see Files and Examples). The file is composed of two tables: changes and links.

Use kc --print config to inspect configuration properties. For example, kc --print config file prints the raw configuration file, while kc --print config path prints the configuration file path.

changes

A single-key table, where the key is labels: an array that specifies which change labels may be used when introducing a new change. If the array is non-empty, kc allows only changes whose labels match at most one of the array members. Otherwise, if the array is empty (not unset, just empty), kc ignores change labels and treats them as change text instead. By default, changes.labels is set to an array comprising of: Added, Removed, Changed, Security, Fixed, Deprecated. Note that, as mentioned in the preamble of the Commands section, when introducing a change, the label may be specified as a case-insensitive prefix, i.e., a label of a, add or ADD is equivalent to Added.

links

A multi-key table, where each key specifies the format for a link type. If a link type does not have a format defined, no links are generated for that particular type.

unreleased

The format for the Unreleased section link. ​
Placeholders: {PREVIOUS}.

The link is generated when the template contains {PREVIOUS} and a previous release exists. If the template is non-empty and does not contain {PREVIOUS}, it is always generated.

initial-release

The format for the initial release (the bottom-most release) link. ​
Placeholders: {CURRENT}.

release

The format for intermediary release (any non-initial release) links. ​
Placeholders: {CURRENT}, {PREVIOUS}.

mention

The format for @-style mention links. ​
Placeholders: {MENTION}.

Placeholders

{CURRENT}

The version string for the current release.

{PREVIOUS}

The version string for the previous release.

{MENTION}

The part after the at symbol in an @-style mention.

Environment

kc consults the VISUAL and EDITOR environment variables to determine which text editor to use when editing a release. If neither is set, kc prompts the user to specify an executable name instead.

Files

.kcrc

The default configuration file. At runtime, kc attempts to load it from the working directory. If no configuration file exists, kc walks up the directory tree until a configuration file is found or the directory tree is exhausted. (The user’s configuration directory is not consulted.)

kc always loads a default internal configuration prior to loading a user-specified configuration file.

CHANGELOG.md

The default changelog file. The loading process is the same as for the configuration file.

The filename is case-insensitive and may also be one of: RELEASE.md, RELEASES.md, RELEASE-NOTES.md, RELEASE_NOTES.md, RELEASENOTES.md, or NEWS.md.

Notes

kc does not require nor use git.

Examples

Initialize and inspect a changelog file:

$ kc --init
Title [Changelog]: <RETURN>
$ kc --print changelog file
# Changelog

## Unreleased
$ kc --print changelog path
CHANGELOG.md

Initialize and inspect a configuration file:

$ kc --init conf github
Repository [user/repository]: xuoe/kc<RETURN>
$ kc --print conf path
.kcrc
$ kc --print conf file
[links]
  initial-release = "https://github.com/xuoe/kc/releases/tag/{CURRENT}"
  mention = "https://github.com/{MENTION}"
  release = "https://github.com/xuoe/kc/compare/{PREVIOUS}...{CURRENT}"
  unreleased = "https://github.com/xuoe/kc/compare/{PREVIOUS}...HEAD"

[changes]
  labels = [
    "Added",
    "Removed",
    "Changed",
    "Security",
    "Fixed",
    "Deprecated",
  ]

Create a changelog, append a change, cut a release:

$ kc --init
Title [Changelog]: <RETURN>
$ kc a This is an example change.
$ kc --print changelog file
# Changelog

## Unreleased

### Added

- This is an example change.
$ kc --release min
0.1.0
$ kc --print ch.f # shorthand for "changelog file"
# Changelog

## 0.1.0 - 2019-12-20

### Added

- This is an example change.
$ kc --list
0.1.0

Delete releases:

$ kc --list
0.3.0
0.2.2
0.2.1
0.2.0
0.1.1
0.1.0
$ kc --delete 0.1
Releases [2/6]:

  0.1.1
  0.1.0

Press [Return] to delete the above or apply a different pattern: <RETURN>
Are you sure you want to delete 2 releases? [yN] y
$ kc --list
0.3.0
0.2.2
0.2.1
0.2.0

Print the path to the active changelog:

$ touch CHANGELOG.md
$ mkdir -p a/b/c; cd a/b/c
$ kc --print changelog path
../../../CHANGELOG.md

License

kc is licensed under the MIT license.