{"id":51891907,"url":"https://github.com/marcuwynu23/git-rndocs","last_synced_at":"2026-07-26T05:01:29.410Z","repository":{"id":369739683,"uuid":"1291282909","full_name":"marcuwynu23/git-rndocs","owner":"marcuwynu23","description":"a cli tool that turns your commit history into polished, human-readable release notes. ","archived":false,"fork":false,"pushed_at":"2026-07-11T06:28:57.000Z","size":127,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-26T00:14:01.357Z","etag":null,"topics":["changelog","documentation","git","release-management","release-notes"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marcuwynu23.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"custom":["https://paypal.me/wynumarcu23"]}},"created_at":"2026-07-06T17:00:20.000Z","updated_at":"2026-07-11T06:28:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/marcuwynu23/git-rndocs","commit_stats":null,"previous_names":["marcuwynu23/git-rndocs"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/marcuwynu23/git-rndocs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcuwynu23%2Fgit-rndocs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcuwynu23%2Fgit-rndocs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcuwynu23%2Fgit-rndocs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcuwynu23%2Fgit-rndocs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcuwynu23","download_url":"https://codeload.github.com/marcuwynu23/git-rndocs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcuwynu23%2Fgit-rndocs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35901460,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-26T02:00:06.503Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["changelog","documentation","git","release-management","release-notes"],"created_at":"2026-07-26T05:01:28.505Z","updated_at":"2026-07-26T05:01:29.392Z","avatar_url":"https://github.com/marcuwynu23.png","language":"Go","funding_links":["https://paypal.me/wynumarcu23"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# git-rndocs\n\n\u003c!-- \u003cimg title=\"\" src=\"./docs/assets/logo-2.svg\" alt=\"\" width=\"208\"\u003e --\u003e\n\n\u003ca href=\"https://github.com/marcuwynu23/git-rndocs/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/marcuwynu23/git-rndocs\" alt=\"GitHub release\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/marcuwynu23/git-rndocs/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/marcuwynu23/git-rndocs?logo=github\" alt=\"License\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/marcuwynu23/git-rndocs/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/marcuwynu23/git-rndocs?style=flat-square\u0026logo=github\" alt=\"Stars\"\u003e\u003c/a\u003e\n\u003cimg src=\"https://img.shields.io/github/go-mod/go-version/marcuwynu23/git-rndocs\" alt=\"Go version\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/Go-%3E%3D1.22-blue\" alt=\"Go version\"\u003e\n\n\u003cstrong\u003eProfessional release notes from Git history.\u003c/strong\u003e Go-native CLI tool. Analyzes commits, detects versions, and generates structured Markdown release notes with a single command.\n\n➡️ **[Read the full user guide →](USER-GUIDE.md)**\n\n\u003c/div\u003e\n\n## Table of Contents\n\n- [What Is git-rndocs?](#what-is-git-rndocs)\n- [Use Cases](#use-cases)\n- [Benefits for Developers](#benefits-for-developers)\n- [Advantages Over Other Tools](#advantages-over-other-tools)\n- [User Guide](USER-GUIDE.md)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [CLI Commands](#cli-commands)\n- [Configuration](#configuration)\n- [Templates](#templates)\n- [Conventional Commits](#conventional-commits)\n- [Output Structure](#output-structure)\n- [Example Output](#example-output)\n- [CI/CD Integration](#cicd-integration)\n- [Development](#development)\n- [Architecture](#architecture)\n\n## What Is git-rndocs?\n\n**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.\n\n### What It Does\n\n- **Scans** your Git tags to detect versions (SemVer, custom prefixes, annotated or lightweight)\n- **Collects** every commit between version boundaries\n- **Parses** each commit against the [Conventional Commits](https://www.conventionalcommits.org/) specification\n- **Categorizes** changes into clear sections: Features, Bug Fixes, Performance, Documentation, Breaking Changes, and more\n- **Detects** breaking changes (`!` or `BREAKING CHANGE` footer), issue references (`#123`), and pull request links (`#42`)\n- **Counts** contributors and generates statistics (files changed, insertions, deletions)\n- **Outputs** beautiful Markdown files — either through a built-in professional template or fully customisable Go templates\n- **Publishes** directly to GitHub Releases with `git rndocs release --upload`\n\n### Why Use It?\n\n**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**.\n\n| Problem | How git-rndocs Solves It |\n|---|---|\n| Writing changelogs is tedious and error-prone | **Automated** — generated from real commit data, zero manual effort |\n| Inconsistent formatting across releases | **Standardised** — every release follows the same structure |\n| Easy to miss breaking changes | **Surfaced automatically** — from `!` or `BREAKING CHANGE` footers |\n| Contributors go uncredited | **Detected and listed** — sorted by commit count |\n| No connection between commits and issues/PRs | **Linked automatically** — `#123` and `#42` references extracted |\n| Manual copy-paste to GitHub Releases | **One command** — `git rndocs release --upload` |\n| Different teams want different formats | **Customisable** — bring your own Go templates |\n| CI pipelines need to publish notes | **CI-native** — runs in any shell, anywhere |\n\n### The Philosophy\n\ngit-rndocs follows three principles:\n\n1. **Minimal setup, maximum value.** One command (`git rndocs init`) scaffolds everything. If you write Conventional Commits, you get release notes for free.\n2. **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.\n3. **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.\n\n## Use Cases\n\n| Scenario                    | How git-rndocs Helps                                                                   |\n| --------------------------- | -------------------------------------------------------------------------------------- |\n| **Open-source maintainers** | Automate changelog generation for every release. Never forget to credit a contributor. |\n| **CI/CD pipelines**         | Run `git rndocs generate` on every tag push. Publish release notes automatically.      |\n| **Monorepo teams**          | Generate release notes per component or per version range.                             |\n| **Release managers**        | Preview notes before publishing with `--dry-run`. Control exactly what gets included.  |\n| **SaaS / internal tools**   | Keep stakeholders informed with professional release notes on every deploy.            |\n| **Compliance / auditing**   | Maintain a permanent, structured record of every change per release.                   |\n\n## Benefits for Developers\n\n- **Zero manual effort** — one command replaces hours of copy-pasting commit messages\n- **Consistent formatting** — every release note follows the same structure, every time\n- **Less context switching** — stay in the terminal; no need to open a docs tool\n- **Catch missing context** — breaking changes and issue references are surfaced automatically\n- **CI-native** — runs in GitHub Actions, GitLab CI, CircleCI, Jenkins, or any shell\n- **Contributor recognition** — automatically lists and sorts contributors by commit count\n- **GitHub-ready** — uploads directly as a GitHub Release with `git rndocs release --upload`\n- **Fully customizable** — templates, config, include/exclude filters — adapt it to your team's style\n\n## Advantages Over Other Tools\n\n| Aspect                    | git-rndocs                                           | git-cliff                      | auto-changelog                 | semantic-release            | handwritten CHANGELOG.md |\n| ------------------------- | ---------------------------------------------------- | ------------------------------ | ------------------------------ | --------------------------- | ------------------------ |\n| **Setup time**            | ~10 seconds (`git rndocs init`)                      | Minutes (config file required) | Minutes (npm install + config) | Hours (full pipeline setup) | None, but ongoing effort |\n| **Conventional Commits**  | Full parser with scopes, footers, breaking changes   | Basic regex matching           | Basic keyword matching         | Limited to bump logic       | N/A (manual)             |\n| **GitHub Releases**       | Built-in (`--upload` via CLI or API)                 | Plugin required                | Not built-in                   | Native                      | Manual copy-paste        |\n| **Templates**             | Go templates (3 built-in + custom)                   | Tera templates                 | Handlebars                     | Fixed format                | Any format but manual    |\n| **Contributor detection** | Automatic, sorted by commit count                    | Basic                          | Not included                   | Not included                | Manual                   |\n| **Statistics**            | Files changed, insertions/deletions, category counts | Limited                        | Not included                   | Not included                | Not included             |\n| **Monorepo support**      | `--from` / `--to` ranges + custom config             | Yes                            | Limited                        | Per-package setup           | Manual                   |\n| **Dry-run / preview**     | `--dry-run` and `preview` subcommand                 | `--dry-run`                    | `--dry-run`                    | Not available               | N/A                      |\n| **Commit filtering**      | Include/exclude by type, group unknown commits       | Regex-based filtering          | Type-based filtering           | Not available               | N/A                      |\n| **Release automation**    | `release` subcommand with draft/prerelease           | Git hooks                      | Not built-in                   | Full pipeline               | None                     |\n| **Runtime**               | Single static binary, no deps                        | Rust binary                    | Requires Node.js/npm           | Requires Node.js            | None                     |\n\nIf you already write Conventional Commits, git-rndocs gives you release notes for free — no extra tooling, no configuration rabbit holes, no runtime dependencies.\n\n## Installation\n\n```bash\ngo install github.com/marcuwynu23/git-rndocs@latest\n```\n\nOr download a binary from the [releases page](https://github.com/marcuwynu23/git-rndocs/releases).\n\n## Quick Start\n\nFor a complete walkthrough including installation, configuration, CI/CD, and troubleshooting, see the **[User Guide](USER-GUIDE.md)**.\n\n```bash\n# Initialize in your project\ngit rndocs init\n\n# Generate release notes\ngit rndocs generate\n\n# Preview in terminal\ngit rndocs preview\n\n# Validate setup\ngit rndocs validate\n```\n\n## CLI Commands\n\n### `generate`\n\nGenerate release notes from Git history.\n\n```bash\ngit rndocs generate\ngit rndocs generate --latest\ngit rndocs generate --version v2.0.0\ngit rndocs generate --from v1.0.0 --to HEAD\ngit rndocs generate --all\ngit rndocs generate --output ./docs/releases\ngit rndocs generate --template github\ngit rndocs generate --dry-run\ngit rndocs generate --overwrite\n```\n\n### `preview`\n\nPreview release notes in the terminal without writing files.\n\n```bash\ngit rndocs preview\ngit rndocs preview --latest\n```\n\n### `validate`\n\nValidate repository tags, history, and configuration.\n\n```bash\ngit rndocs validate\n```\n\n### `init`\n\nInitialize git-rndocs in your project.\n\n```bash\ngit rndocs init\n```\n\nCreates `.git-rndocs.yaml`, `docs/releases/`, and `templates/default.md`.\n\n### `config`\n\nView and manage configuration.\n\n```bash\ngit rndocs config\ngit rndocs config --get output\n```\n\n### `release`\n\nGenerate release notes and optionally create a GitHub Release.\n\n```bash\ngit rndocs release\ngit rndocs release --upload\ngit rndocs release --draft\ngit rndocs release --prerelease\n```\n\n## Configuration\n\n`.git-rndocs.yaml`:\n\n```yaml\noutput: docs/releases\ntemplate: default\nrelease_name: \"Version {{ .Version }}\"\ninclude:\n  - feat\n  - fix\n  - perf\nexclude:\n  - chore\ngroup_unknown: true\ngithub:\n  upload: false\ncontributors: true\nstatistics: true\n```\n\n## Templates\n\nBuilt-in templates:\n\n- `default` - Professional Markdown release notes\n- `github` - GitHub-flavored release notes\n- `minimal` - Minimal release notes\n\nCustom templates use Go templates:\n\n```markdown\n# Release Notes\n\n## Version\n\n{{ .Version }}\n\n{{ range .Sections }}\n\n## {{ .Title }}\n\n{{ range .Commits }}\n\n- {{ .Header }}\n  {{ end }}\n  {{ end }}\n```\n\n## Conventional Commits\n\nRecognized commit types:\n\n- `feat` - Features\n- `fix` - Bug Fixes\n- `perf` - Performance\n- `docs` - Documentation\n- `refactor` - Refactoring\n- `style` - Style\n- `build` - Build\n- `ci` - CI/CD\n- `test` - Tests\n- `chore` - Maintenance\n- `revert` - Reverts\n\nBreaking changes are detected via `!` or `BREAKING CHANGE` footer.\n\n## Output Structure\n\n```\ndocs/\n└── releases/\n    ├── v1.0.0/\n    │   └── RELEASE-NOTES.md\n    ├── v1.1.0/\n    │   └── RELEASE-NOTES.md\n    └── v2.0.0/\n        └── RELEASE-NOTES.md\n```\n\n## Example Output\n\n```markdown\n# Release Notes\n\n## Version\n\nv2.0.0\n\n## Release Date\n\n2026-07-07\n\n---\n\n## Features\n\n- **auth:** Added OAuth2 login (#123)\n- Added GitHub Release upload\n\n## Bug Fixes\n\n- Fixed Windows path detection\n\n## Breaking Changes\n\n- CLI configuration renamed\n\n## Contributors\n\n- Alice (5 commits)\n- Bob (3 commits)\n\n## Full Changelog\n\nv1.1.0...v2.0.0\n```\n\n## CI/CD Integration\n\n### GitHub Actions\n\n```yaml\nname: Release Notes\non:\n  push:\n    tags:\n      - \"v*\"\njobs:\n  release:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-go@v5\n      - run: go install github.com/marcuwynu23/git-rndocs@latest\n      - run: git rndocs generate\n      - run: git rndocs release --upload\n```\n\n## Development\n\n### Prerequisites\n\n- Go 1.22+\n\n### Build\n\n```bash\nmake build\n```\n\n### Test\n\n```bash\nmake test\n```\n\n### Coverage\n\n```bash\nmake cover\n```\n\n### Project Structure\n\n```\ncmd/             - CLI commands\ninternal/\n  app/           - Application orchestration\n  config/        - Configuration management\n  contributors/  - Contributor detection\n  git/           - Git operations\n  github/        - GitHub Releases integration\n  markdown/      - Markdown generation\n  output/        - File output\n  parser/        - Conventional Commit parsing\n  releasenotes/  - Release notes generation\n  stats/         - Statistics collection\n  template/      - Template engine\ntemplates/       - Built-in templates\n```\n\n## Architecture\n\nThe project follows Clean Architecture principles:\n\n- **Git access** is isolated behind interfaces\n- **Business logic** is separated from CLI commands\n- **Dependency injection** connects components\n- **Single responsibility** per package\n\n## License\n\nApache 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.\n\nHappy Coding! 🚀\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcuwynu23%2Fgit-rndocs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcuwynu23%2Fgit-rndocs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcuwynu23%2Fgit-rndocs/lists"}