https://github.com/marcuwynu23/git-rndocs
a cli tool that turns your commit history into polished, human-readable release notes.
https://github.com/marcuwynu23/git-rndocs
changelog documentation git release-management release-notes
Last synced: 1 day ago
JSON representation
a cli tool that turns your commit history into polished, human-readable release notes.
- Host: GitHub
- URL: https://github.com/marcuwynu23/git-rndocs
- Owner: marcuwynu23
- License: apache-2.0
- Created: 2026-07-06T17:00:20.000Z (21 days ago)
- Default Branch: main
- Last Pushed: 2026-07-11T06:28:57.000Z (16 days ago)
- Last Synced: 2026-07-26T00:14:01.357Z (1 day ago)
- Topics: changelog, documentation, git, release-management, release-notes
- Language: Go
- Homepage:
- Size: 124 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
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 →](USER-GUIDE.md)**
## Table of Contents
- [What Is git-rndocs?](#what-is-git-rndocs)
- [Use Cases](#use-cases)
- [Benefits for Developers](#benefits-for-developers)
- [Advantages Over Other Tools](#advantages-over-other-tools)
- [User Guide](USER-GUIDE.md)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [CLI Commands](#cli-commands)
- [Configuration](#configuration)
- [Templates](#templates)
- [Conventional Commits](#conventional-commits)
- [Output Structure](#output-structure)
- [Example Output](#example-output)
- [CI/CD Integration](#cicd-integration)
- [Development](#development)
- [Architecture](#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](https://www.conventionalcommits.org/) 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
```bash
go install github.com/marcuwynu23/git-rndocs@latest
```
Or download a binary from the [releases page](https://github.com/marcuwynu23/git-rndocs/releases).
## Quick Start
For a complete walkthrough including installation, configuration, CI/CD, and troubleshooting, see the **[User Guide](USER-GUIDE.md)**.
```bash
# 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.
```bash
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.
```bash
git rndocs preview
git rndocs preview --latest
```
### `validate`
Validate repository tags, history, and configuration.
```bash
git rndocs validate
```
### `init`
Initialize git-rndocs in your project.
```bash
git rndocs init
```
Creates `.git-rndocs.yaml`, `docs/releases/`, and `templates/default.md`.
### `config`
View and manage configuration.
```bash
git rndocs config
git rndocs config --get output
```
### `release`
Generate release notes and optionally create a GitHub Release.
```bash
git rndocs release
git rndocs release --upload
git rndocs release --draft
git rndocs release --prerelease
```
## Configuration
`.git-rndocs.yaml`:
```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:
```markdown
# 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
```markdown
# 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
```yaml
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
```bash
make build
```
### Test
```bash
make test
```
### Coverage
```bash
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! 🚀