🪵 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 .

📖 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
  -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

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