cl

cl is a command line tool that assists with the management of unreleased changes when using the Keep a Changelog format in a team setting.

cl utilizes a .cl directory in the root of your git repository to store changes. Each branch will log its changes to it's own .yml file that matches the branch name. This will allow developers to log their changes in an atomic way and avoid unnecessary merge conflicts.

Installation

Homebrew

$ brew install marcaddeo/clsuite/cl

Debian

$ curl -LO https://github.com/marcaddeo/cl/releases/download/0.9.0/cl_0.9.0_amd64.deb
$ sudo dpkg -i cl_0.9.0_amd64.deb

Linux

$ curl -LO https://github.com/marcaddeo/cl/releases/download/0.9.0/cl-0.9.0-x86_64-unknown-linux-musl.tar.gz
$ tar czvf cl-0.9.0-x86_64-unknown-linux-musl.tar.gz
$ sudo mv cl /usr/local/bin/cl

Cargo

$ cargo install cl

Usage

cl 0.9.0
Marc Addeo <hi@marc.cx>
A command line tool for recording changes to be collected for use in a Keep A Changelog formatted CHANGELOG.md

USAGE:
    cl [FLAGS] [OPTIONS] [SUBCOMMAND]

FLAGS:
    -n, --no-headings    Hides the headings when output format is Markdown or YAML
    -h, --help           Prints help information
    -V, --version        Prints version information

OPTIONS:
    -f, --format <format>    Sets the output format to be used when displaying all changes [default: markdown]
                             [possible values: json, yaml, yml, markdown, md]

SUBCOMMANDS:
    added         Creates a change entry to be placed in the Added section of the CHANGELOG [aliases: add]
    changed       Creates a change entry to be placed in the Changed section of the CHANGELOG [aliases: change]
    deprecated    Creates a change entry to be placed in the Deprecated section of the CHANGELOG [aliases: deprecate]
    removed       Creates a change entry to be placed in the Removed section of the CHANGELOG [aliases: remove]
    fixed         Creates a change entry to be placed in the Fixed section of the CHANGELOG [aliases: fix]
    security      Creates a change entry to be placed in the Security section of the CHANGELOG
    edit          Opens the change file for direct editing
    yank          Mark a specific release as [YANKED]
    aggregate     Aggregate change entries into the Unreleased section of the CHANGELOG

Examples

Viewing unreleased changes

When running cl without a subcommand, all unreleased changes will be displayed. This can be formatted as Markdown, JSON, or YAML.

$ cl
## [Unreleased]
### Added
- Added a new feature to the website

### Removed
- Removed extraneous files from the repository

### Security
- Fixed a security flaw in the main authentication service

And as YAML:

$ cl -f yaml
---
- added: Added a new feature to the website
- security: Fixed a security flaw in the main authentication service
- removed: Removed extraneous files from the repository

Adding change entries

There is a subcommand for each type of change entry. Running the subcommand will add the change entry to the appropriate change file in the storage directory.

cl-added
Creates a change entry to be placed in the Added section of the CHANGELOG

USAGE:
    cl added <DESCRIPTION>...

FLAGS:
    -h, --help    Prints help information

ARGS:
    <DESCRIPTION>...    The description of this change entry

For example:

$ cl added Added a new feature to the website

Editing the change file

If you make a typo or need to remove a change entry, you can run the edit subcommand to open the change file in your text editor. This will try to find your text editor using the $VISUAL and $EDITOR environment variables.

$ cl edit

Yanking a release

Sometimes a release doesn't go as plan after the fact, and needs to be yanked from history. To do so, simply type cl yank 1.2.3 where 1.2.3 is the release you wish to yank. This will tag the release as [YANKED] and remove it's link from the CHANGELOG.

Aggregating unreleased changes

After you've made some changes and they've been merged, you'll likely want to aggregate your cl entries into the actual CHANGELOG.md file so they can be easily viewed by users. This can be achieved with the aggregate subcommand.

$ cl aggregate

This will take any change entries in the .cl directory, put them into the CHANGELOG.md file, and then remove them and any empty directories within the .cl directory.

This command is useful to run via CI after a pull request has been merged.