cl

cl 是一个命令行工具，帮助团队在采用 Keep a Changelog 格式时管理未发布变更。

cl 使用 Git 仓库根目录下的 .cl 目录来存储变更。每个分支都会将其变更记录到与分支名匹配的 .yml 文件中。这允许开发者以原子的方式记录变更，从而避免不必要的合并冲突。

安装

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

使用方法

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

示例

查看未发布变更

当不带子命令运行 cl 时，将显示所有未发布变更。这可以格式化为 Markdown、JSON 或 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

以及 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

添加变更条目

为每种类型的变更条目都有一个子命令。运行子命令会将变更条目添加到存储目录中相应的变更文件。

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

例如

$ cl added Added a new feature to the website

编辑变更文件

如果您出现拼写错误或需要删除变更条目，可以运行 edit 子命令以在文本编辑器中打开变更文件。这将尝试使用 $VISUAL 和 $EDITOR 环境变量来查找您的文本编辑器。

$ cl edit

撤回版本

有时，发布的事实上并不按计划进行，需要从历史中撤回。要这样做，只需键入 cl yank 1.2.3，其中 1.2.3 是您要撤回的版本。这将把版本标记为 [YANKED] 并从变更日志中移除它的链接。

聚合未发布的变化

在您做了些更改并且它们已被合并后，您可能会想要将您的 cl 条目聚合到实际的 CHANGELOG.md 文件中，以便用户可以轻松查看。这可以通过 aggregate 子命令实现。

$ cl aggregate

这将从 .cl 目录中获取任何更改条目，将它们放入 CHANGELOG.md 文件中，然后从 .cl 目录中移除它们以及任何空目录。

此命令在拉取请求合并后通过 CI 运行非常有用。