Giter Club home page Giter Club logo

cl's Introduction

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 <[email protected]>
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.

cl's People

Contributors

marcaddeo avatar

Stargazers

avatar avatar avatar avatar

Watchers

avatar avatar

cl's Issues

cl should show all unreleased changes

cl is currently only displaying the entries from the change storage. With our current automated workflow, which will aggregate the changes from change storage and put them into the CHANGELOG.md unreleased section on PR merge, the usefulness of this is limited.

As a user of cl I'd like to be able to see all changes that are unreleased, whether they're in the CHANGELOG.md or in the .cl directory.

Error when branch directory doesn't exist

When trying to run cl added something on a branch such as JIRA-1234/summary-here, cl will show the following error because the .cl/JIRA-1234 directory does not exist.

image

Add an aggregate command

We should have an aggregate command that takes the items from the .cl directory, and aggregates them all into the CHANGELOG.md's Unreleased section.

Currently using this in our CI:

  $CLPARSE CHANGELOG.md -f json | cat - <($CL -f json) | \
    $JQ -s ".[0].releases[0].changes+=.[1] | .[0]" | \
    $CLPARSE - > CHANGELOG.md.new \
    && mv CHANGELOG.md.new CHANGELOG.md

  find .cl -name "*.yml" -type f -delete

But it no longer works because cl now displays changes from the Unreleased section, as well as the .cl directory. So whenever you run the command above, it causes the CHANGELOG to duplicate all entries.

build fails

When installing cl via cargo install cl I'm running into the following error:

  Compiling derive-getters v0.1.1
error[E0433]: failed to resolve: could not find `__rt` in `quote`
   --> /Users/d34dl0ck/.cargo/registry/src/github.com-1ecc6299db9ec823/err-derive-0.1.6/src/lib.rs:145:63
    |
145 | fn display_body(s: &synstructure::Structure) -> Option<quote::__rt::TokenStream> {
    |                                                               ^^^^ could not find `__rt` in `quote`

error: aborting due to previous error

For more information about this error, try `rustc --explain E0433`.
error: could not compile `err-derive`

To learn more, run the command again with --verbose.
warning: build failed, waiting for other jobs to finish...
error: failed to compile `cl v0.9.0`, intermediate artifacts can be found at `/var/folders/m8/084p1v0x4770rpwpkrgl5b6h0000gn/T/cargo-installP3F7eQ`

Caused by:
  build failed

Context

❯ cargo --version && rustc --version
cargo 1.49.0 (d00d64df9 2020-12-05)
rustc 1.49.0 (e1884a8e3 2020-12-29)

Suggestion

recently I discovered https://dependabot.com and added them to my rust crates, to keep all dependencies up to date.

Add an init command

It would be useful if there was an init command that would just create .cl/.gitkeep. When the .cl folder doesn't exist, the error message should say to use init.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.