parse-changelog
A simple changelog parser, written in Rust.
Installation
CLI
To use this crate as a command line tool, run the following command:
Alternatively, download compiled binaries from GitHub Releases.
Library
To use this crate as a library, add this to your Cargo.toml
:
[]
= { = "0.2", = false }
Note: When using this crate as a library, we recommend disabling the default features because the default features enable CLI-related dependencies and the library part of this crate does not use them.
Compiler support: requires rustc 1.45+
Usage (CLI)
parse-changelog
command parses changelog and returns a release note for the
specified version.
USAGE:
parse-changelog [OPTIONS] <PATH> [VERSION]
OPTIONS:
-t, --title Returns title instead of notes
--version-format <PATTERN> Specify version format
--prefix <PATTERN> Alias for --prefix-format
--prefix-format <PATTERN> Specify prefix format
-h, --help Prints help information
-V, --version Prints version information
ARGS:
<PATH> Path to the changelog file (use '-' for standard input)
<VERSION> Specify version (by default, select the latest release)
Example: Get Rust's release notes
Get the release note for version 1.46.0 from Rust's release notes:
|
Example: Get Cargo's changelog
In Cargo's changelog,
the title starts with "Cargo ", and the patch version is omitted. This is a
format parse-changelog
don't support by default, so use --prefix
and
--version-format
to specify a custom format. For example:
|
--prefix
is the same as Parser::prefix_format
and --version-format
is
the same as Parser::version_format
. See documentation of those methods for
more information.
Example: Create a new GitHub release from changelog
With GitHub CLI:
tag=...
version=...
# Get notes for $version from CHANGELOG.md.
notes=
# Create a new GitHub release with GitHub CLI.
With softprops/action-gh-release GitHub Action:
name: Release
on:
push:
tags:
- "v*"
jobs:
release:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2
- name: Install parse-changelog
run: cargo install parse-changelog
- name: Generate Changelog
run: |
# Get version from github ref (remove 'refs/tags/' and prefix 'v')
version="${GITHUB_REF#refs/tags/v}"
# Get notes for $version from CHANGELOG.md.
parse-changelog CHANGELOG.md "$version" > ${{ github.workflow }}-CHANGELOG.txt
- name: Release
uses: softprops/action-gh-release@v1
with:
body_path: ${{ github.workflow }}-CHANGELOG.txt
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Examples (Library)
let changelog = "\
## 0.1.2 - 2020-03-01
- Bug fixes.
## 0.1.1 - 2020-02-01
- Added `Foo`.
- Added `Bar`.
## 0.1.0 - 2020-01-01
Initial release
";
// Parse changelog.
let changelog = parse.unwrap;
// Get the latest release.
assert_eq!;
assert_eq!;
assert_eq!;
// Get the specified release.
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
See documentation for more information on
parse-changelog
as a library.
Format
By default, this crate is intended to support markdown-based changelogs that have the title of each release starts with the version format based on Semantic Versioning. (e.g., Keep a Changelog's changelog format.)
Headings
The heading for each release must be Atx-style (1-6 #
) or
Setext-style (=
or -
in a line under text), and the heading levels
must match with other releases.
Atx-style headings:
Setext-style headings:
0.1.0
=====
0.1.0
Titles
The title of each release must start with a text or a link text (text with
[
and ]
) that starts with a valid version format. For example:
description...
description...
You can also include characters before the version as prefix.
## Version 0.1.0
^^^^^^^^
By default only "v", "Version " and "Release " are allowed as prefixes and
can be customized using the Parser::prefix_format
method
(--prefix-format
option if command line).
You can freely include characters after the version (this crate does not parse it).
# 0.1.0 - 2020-01-01
^^^^^^^^^^^^^
Versions
## v0.1.0 -- 2020-01-01
^^^^^
The default version format is
MAJOR.MINOR.PATCH(-PRE_RELEASE)?(+BUILD_METADATA)?
, and is
based on Semantic Versioning. (Pre-release version and build
metadata are optional.)
This is parsed using the following regular expression:
^\d+\.\d+\.\d+(-[\w\.-]+)?(\+[\w\.-]+)?$
To customize the version format, use the Parser::version_format
method
(--version-format
option if command line).
License
Licensed under either of Apache License, Version 2.0 or MIT license at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.