relnotes

Release notes from conventional commits — auto-generate professional changelogs with zero config.

A fast, zero-dependency Rust CLI tool that parses your Git history and generates beautiful release notes following the Conventional Commits specification. Works out of the box — just run relnotes generate in any Git repo.

---

Features

• 🔍 Auto-detect latest tag — no need to specify ranges manually
• 📝 Markdown output — pretty CHANGELOG.md or custom format
• 🧩 JSON output — machine-readable release notes
• 🔥 Breaking changes detection — both ! and BREAKING CHANGE: body syntax
• 📊 Group by type — Features, Bug Fixes, Documentation, and more
• ⚡ Scope sorting — commits sorted by scope within each type section
• 🔧 Configurable — via relnotes.toml or CLI flags
• 🎯 Range selection — --from v1.0.0 --to v2.0.0 or --since 2024-01-01
• 🏎️ Blazing fast — built in Rust with libgit2

Installation

Using Cargo

cargo install --git https://github.com/AFS-Agentics/relnotes

From Source

git clone https://github.com/AFS-Agentics/relnotes
cd relnotes
cargo install --path .

Quick Start

# Navigate to any Git repo with conventional commits
cd my-project

# Generate CHANGELOG.md
relnotes generate

# Generate JSON output
relnotes generate --format json

# Generate release notes for a specific version range
relnotes generate --from v1.0.0 --to v2.0.0

# Generate with custom output file
relnotes generate -o RELEASE_NOTES.md

Usage

relnotes — Automated release notes from conventional commits

USAGE:
  relnotes [SUBCOMMAND]

SUBCOMMANDS:
  generate    Generate release notes
  init        Create a relnotes.toml config
  help        Print this message or help for subcommand
  version     Print version

OPTIONS:
  -h, --help    Print help information
  -V, --version Print version information

Generate Options

Flag	Description
--from <ref>	Start ref (e.g., v0.1.0)
--to <ref>	End ref (default: HEAD)
--since <date>	Commits since date (YYYY-MM-DD)
--format <fmt>	Output format: md or json
-o, --output <path>	Output file path
-c, --config <path>	Path to config file

Init

# Create a relnotes.toml in the current directory
relnotes init

Configuration

Create a relnotes.toml file at your project root:

[project]
name = "my-project"
version = "0.1.0"
# repository = "https://github.com/user/repo"

[generate]
output_format = "md"
output_file = "CHANGELOG.md"
header_template = "# Changelog"
include_scope = true
group_by_type = true

[tags]
version_prefix = "v"
include_unreleased = true

Output Examples

Markdown (default)

# Changelog

## [v1.0.0] - 2025-01-15

### Features
- **auth**: Add OAuth login support
- **core**: Rewrite caching layer
  (abc1234)

### Bug Fixes
- **parser**: Fix null pointer in edge case
  (def5678)

### Breaking Changes
- **api**: Remove deprecated v1 endpoints
  (ghi9012)

JSON

{
  "project": "my-project",
  "version": "v1.0.0",
  "date": "2025-01-15",
  "sections": {
    "Features": [
      { "hash": "abc1234", "type": "feat", "scope": "auth", "description": "Add OAuth login support", "breaking": false }
    ]
  }
}

Conventional Commit Format

relnotes parses commits following the Conventional Commits specification:

type(scope): description

body

Type	Section
feat	Features
fix	Bug Fixes
docs	Documentation
style	Styling
refactor	Refactoring
perf	Performance
test	Tests
build	Build System
ci	Continuous Integration
chore	Chores
revert	Reverts

Breaking changes are detected via type!: or BREAKING CHANGE: in the commit body.

Development

# Run tests
cargo test

# Build release binary
cargo build --release

# Run linting
cargo clippy

License

MIT © 2025 AFS Agentics