git-rndocs

README

git-rndocs

Professional release notes from Git history. Go-native CLI tool. Analyzes commits, detects versions, and generates structured Markdown release notes with a single command.

➡️ Read the full user guide →

Table of Contents

• What Is git-rndocs?
• Use Cases
• Benefits for Developers
• Advantages Over Other Tools
• User Guide
• Installation
• Quick Start
• CLI Commands
• Configuration
• Templates
• Conventional Commits
• Output Structure
• Example Output
• CI/CD Integration
• Development
• Architecture

What Is git-rndocs?

git-rndocs is a Git-native CLI tool that automatically generates professional release notes from your commit history. Instead of manually writing changelogs, you run a single command and get structured, categorized Markdown release notes — ready to ship.

What It Does

• Scans your Git tags to detect versions (SemVer, custom prefixes, annotated or lightweight)
• Collects every commit between version boundaries
• Parses each commit against the Conventional Commits specification
• Categorizes changes into clear sections: Features, Bug Fixes, Performance, Documentation, Breaking Changes, and more
• Detects breaking changes (! or BREAKING CHANGE footer), issue references (#123), and pull request links (#42)
• Counts contributors and generates statistics (files changed, insertions, deletions)
• Outputs beautiful Markdown files — either through a built-in professional template or fully customisable Go templates
• Publishes directly to GitHub Releases with git rndocs release --upload

Why Use It?

Release notes are the public face of your work. Yet most teams write them by hand — copying commit messages, guessing what changed, and inevitably missing things. git-rndocs solves this by making release notes a byproduct of your existing Git workflow.

Problem	How git-rndocs Solves It
Writing changelogs is tedious and error-prone	Automated — generated from real commit data, zero manual effort
Inconsistent formatting across releases	Standardised — every release follows the same structure
Easy to miss breaking changes	Surfaced automatically — from ! or BREAKING CHANGE footers
Contributors go uncredited	Detected and listed — sorted by commit count
No connection between commits and issues/PRs	Linked automatically — #123 and #42 references extracted
Manual copy-paste to GitHub Releases	One command — git rndocs release --upload
Different teams want different formats	Customisable — bring your own Go templates
CI pipelines need to publish notes	CI-native — runs in any shell, anywhere

The Philosophy

git-rndocs follows three principles:

1. Minimal setup, maximum value. One command (git rndocs init) scaffolds everything. If you write Conventional Commits, you get release notes for free.
2. Your process stays yours. The tool reads your Git history — it doesn't impose a workflow, a platform, or a runtime. No daemons, no servers, no databases.
3. Production-grade from day one. Single static binary, zero dependencies, cross-platform, built with Go. It works the same on your laptop, a GitHub Actions runner, or a bare-metal CI server.

Use Cases

Scenario	How git-rndocs Helps
Open-source maintainers	Automate changelog generation for every release. Never forget to credit a contributor.
CI/CD pipelines	Run git rndocs generate on every tag push. Publish release notes automatically.
Monorepo teams	Generate release notes per component or per version range.
Release managers	Preview notes before publishing with --dry-run. Control exactly what gets included.
SaaS / internal tools	Keep stakeholders informed with professional release notes on every deploy.
Compliance / auditing	Maintain a permanent, structured record of every change per release.

Benefits for Developers

• Zero manual effort — one command replaces hours of copy-pasting commit messages
• Consistent formatting — every release note follows the same structure, every time
• Less context switching — stay in the terminal; no need to open a docs tool
• Catch missing context — breaking changes and issue references are surfaced automatically
• CI-native — runs in GitHub Actions, GitLab CI, CircleCI, Jenkins, or any shell
• Contributor recognition — automatically lists and sorts contributors by commit count
• GitHub-ready — uploads directly as a GitHub Release with git rndocs release --upload
• Fully customizable — templates, config, include/exclude filters — adapt it to your team's style

Advantages Over Other Tools

Aspect	git-rndocs	git-cliff	auto-changelog	semantic-release	handwritten CHANGELOG.md
Setup time	~10 seconds (git rndocs init)	Minutes (config file required)	Minutes (npm install + config)	Hours (full pipeline setup)	None, but ongoing effort
Conventional Commits	Full parser with scopes, footers, breaking changes	Basic regex matching	Basic keyword matching	Limited to bump logic	N/A (manual)
GitHub Releases	Built-in (--upload via CLI or API)	Plugin required	Not built-in	Native	Manual copy-paste
Templates	Go templates (3 built-in + custom)	Tera templates	Handlebars	Fixed format	Any format but manual
Contributor detection	Automatic, sorted by commit count	Basic	Not included	Not included	Manual
Statistics	Files changed, insertions/deletions, category counts	Limited	Not included	Not included	Not included
Monorepo support	--from / --to ranges + custom config	Yes	Limited	Per-package setup	Manual
Dry-run / preview	--dry-run and preview subcommand	--dry-run	--dry-run	Not available	N/A
Commit filtering	Include/exclude by type, group unknown commits	Regex-based filtering	Type-based filtering	Not available	N/A
Release automation	release subcommand with draft/prerelease	Git hooks	Not built-in	Full pipeline	None
Runtime	Single static binary, no deps	Rust binary	Requires Node.js/npm	Requires Node.js	None

If you already write Conventional Commits, git-rndocs gives you release notes for free — no extra tooling, no configuration rabbit holes, no runtime dependencies.

Installation

go install github.com/marcuwynu23/git-rndocs@latest

Or download a binary from the releases page.

Quick Start

For a complete walkthrough including installation, configuration, CI/CD, and troubleshooting, see the User Guide.

# Initialize in your project
git rndocs init

# Generate release notes
git rndocs generate

# Preview in terminal
git rndocs preview

# Validate setup
git rndocs validate

CLI Commands

generate

Generate release notes from Git history.

git rndocs generate
git rndocs generate --latest
git rndocs generate --version v2.0.0
git rndocs generate --from v1.0.0 --to HEAD
git rndocs generate --all
git rndocs generate --output ./docs/releases
git rndocs generate --template github
git rndocs generate --dry-run
git rndocs generate --overwrite

preview

Preview release notes in the terminal without writing files.

git rndocs preview
git rndocs preview --latest

validate

Validate repository tags, history, and configuration.

git rndocs validate

init

Initialize git-rndocs in your project.

git rndocs init

Creates .git-rndocs.yaml, docs/releases/, and templates/default.md.

config

View and manage configuration.

git rndocs config
git rndocs config --get output

release

Generate release notes and optionally create a GitHub Release.

git rndocs release
git rndocs release --upload
git rndocs release --draft
git rndocs release --prerelease

Configuration

.git-rndocs.yaml:

output: docs/releases
template: default
release_name: "Version {{ .Version }}"
include:
  - feat
  - fix
  - perf
exclude:
  - chore
group_unknown: true
github:
  upload: false
contributors: true
statistics: true

Templates

Built-in templates:

• default - Professional Markdown release notes
• github - GitHub-flavored release notes
• minimal - Minimal release notes

Custom templates use Go templates:

# Release Notes

## Version

{{ .Version }}

{{ range .Sections }}

## {{ .Title }}

{{ range .Commits }}

- {{ .Header }}
  {{ end }}
  {{ end }}

Conventional Commits

Recognized commit types:

• feat - Features
• fix - Bug Fixes
• perf - Performance
• docs - Documentation
• refactor - Refactoring
• style - Style
• build - Build
• ci - CI/CD
• test - Tests
• chore - Maintenance
• revert - Reverts

Breaking changes are detected via ! or BREAKING CHANGE footer.

Output Structure

docs/
└── releases/
    ├── v1.0.0/
    │   └── RELEASE-NOTES.md
    ├── v1.1.0/
    │   └── RELEASE-NOTES.md
    └── v2.0.0/
        └── RELEASE-NOTES.md

Example Output

# Release Notes

## Version

v2.0.0

## Release Date

2026-07-07

---

## Features

- **auth:** Added OAuth2 login (#123)
- Added GitHub Release upload

## Bug Fixes

- Fixed Windows path detection

## Breaking Changes

- CLI configuration renamed

## Contributors

- Alice (5 commits)
- Bob (3 commits)

## Full Changelog

v1.1.0...v2.0.0

CI/CD Integration

GitHub Actions

name: Release Notes
on:
  push:
    tags:
      - "v*"
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
      - run: go install github.com/marcuwynu23/git-rndocs@latest
      - run: git rndocs generate
      - run: git rndocs release --upload

Development

Prerequisites

• Go 1.22+

Build

make build

Test

make test

Coverage

make cover

Project Structure

cmd/             - CLI commands
internal/
  app/           - Application orchestration
  config/        - Configuration management
  contributors/  - Contributor detection
  git/           - Git operations
  github/        - GitHub Releases integration
  markdown/      - Markdown generation
  output/        - File output
  parser/        - Conventional Commit parsing
  releasenotes/  - Release notes generation
  stats/         - Statistics collection
  template/      - Template engine
templates/       - Built-in templates

Architecture

The project follows Clean Architecture principles:

• Git access is isolated behind interfaces
• Business logic is separated from CLI commands
• Dependency injection connects components
• Single responsibility per package

License

Apache 2.0 — you are free to use, modify, distribute, and sublicense this software. In short: do what you want, just don't sue us and keep the original copyright notice.

Happy Coding! 🚀