🪵 cl-parse 🪵

Parse most changelog formats into common structured data formats.

cl-parse is a command-line tool that converts various changelog formats into structured data (JSON, YAML, or TOML). It supports changelogs generated by popular tools like release-please and semantic-release, making it easier to programmatically work with changelog data.

🎭 Example Transformation

Input (CHANGELOG.md):

## [0.4.0](https://github.com/scottmckendry/cl-parse/compare/v0.3.0...v0.4.0) (2025-01-14)

### Features

- **cmd:** `format` option with new YAML & TOML outputs ([7ffb283](https://github.com/scottmckendry/cl-parse/commit/7ffb283))
- **origin:** add support for github issue lookup ([539c4cd](https://github.com/scottmckendry/cl-parse/commit/539c4cd)), closes [#2](https://github.com/scottmckendry/cl-parse/issues/2)

Command:

cl-parse --format yaml --include-body --fetch-item-details -latest

Output:

version: 0.4.0
date: 2025-01-14T00:00:00Z
compareUrl: https://github.com/scottmckendry/cl-parse/compare/v0.3.0...v0.4.0
changes:
  Features:
    - description: "**cmd:** `format` option with new YAML & TOML outputs"
      commit: 7ffb283
    - description: "**origin:** add support for github issue lookup"
      commit: 539c4cd
      commitBody: "adds new flag --fetch-item-details to fetch related items\n\nResolves #2"
      relatedItems:
        - number: 2
          title: "Feature: Programatically Fetch content from PRs and Issues"
          body: "Add an option to support the lookup of PRs and issues..."

✨ Features

• Parses conventional changelog formats
• Supports multiple output formats (JSON, YAML, TOML)
• Can fetch additional context from:
  • Full commit messages
  • Linked GitHub Issues
  • GitHub Pull Requests
  • Azure DevOps Work Items
  • GitLab Issues and Merge Requests

🚀 Supported Git Hosts

• GitHub (github.com)
• Azure DevOps (dev.azure.com)
• GitLab (gitlab.com)

📦 Installation

Pre-built binaries are available for most platforms on the releases page. You can also install the tool from source:

git clone https://github.com/scottmckendry/cl-parse && cd cl-parse
go install .

Nix

Add to your flake inputs:

{
  inputs.cl-parse.url = "github:scottmckendry/cl-parse";
}

Then you can use it in your configuration:

{
  inputs,
  pkgs,
  ...
}:

{
  # Install as a system package
  environment.systemPackages = [
    inputs.cl-parse.packages.${pkgs.system}.default
  ];

  # OR with home-manager
  home.packages = [
    inputs.cl-parse.packages.${pkgs.system}.default
  ];
}

📖 Usage

Basic usage:

cl-parse CHANGELOG.md

# is the same as
cl-parse # looks for a file named CHANGELOG.md in the current directory

⚙️ Options

Flags:
      --fetch-item-details   fetch details for related items (e.g. GitHub issues & PRs)
  -f, --format string        output format (json, yaml, or toml) (default "json")
      --include-body         include the full commit body in changelog entry
      --last int             limit output to the N most recent releases
      --since-days int       limit output to releases within the last N days (UTC)
  -l, --latest              display the most recent version from the changelog
  -r, --release string      display the changelog entry for a specific release
      --token string        token for fetching related items

🌟 Examples

Filter to the last 3 releases:

cl-parse --last 3 CHANGELOG.md

Filter to releases in the last 7 days (inclusive by day, UTC):

cl-parse --since-days 7 CHANGELOG.md

Get the latest release in JSON format:

cl-parse -l CHANGELOG.md

Get a specific release in YAML format:

cl-parse -r v1.0.0 -f yaml CHANGELOG.md

Include full commit messages and fetch related items:

cl-parse --include-body --fetch-item-details --token YOUR_TOKEN CHANGELOG.md

🔐 Authentication

If your repository is private (or you're using Azure DevOps), you'll need to provide a token to fetch related items.

📚 Supported Formats

• Conventional Changelog
• release-please
• semantic-release
• Keep a Changelog

📄 Output

The tool outputs structured data in your chosen format, including:

• Version information
• Release date
• Changes categorized by type (feat, fix, etc.)
• References to issues and pull requests
• Optional full commit messages
• Optional detailed information about linked items