A CLI tool that reads git commit history and outputs well-formatted changelogs, eliminating the manual, error-prone process.

Quick Start • Features • Examples • Contributing

What is this?

SuprLogs is a command‑line utility that scans a Git repository’s commit history and automatically creates a nicely formatted changelog. It is aimed at developers and maintainers who want to produce release notes quickly and consistently.

Example usage:

$ suprlogs changelog --since v1.0.0
## [v1.2.0] - 2024-04-12
### Added
- New user authentication module (feat: add login endpoint)
- Configurable timeout for API calls (feat: introduce timeout setting)
### Fixed
- Resolve crash on empty payload (fix: handle null body)
- Correct typo in validation message (fix: spelling error)

Problem

Developers hate writing changelogs; they often become stale or overly technical, slowing down release documentation.

Features

Feature	Description
Git Log Extraction	Retrieves commits from a range, branch, or date window, optionally excluding merge commits.
Commit Classification	Groups commits into sections such as Added, Fixed, Breaking, Docs using configurable regex patterns.
Templating Engine	Renders the changelog with a built‑in Keep a Changelog template or a custom Jinja2‑like template.
Multi‑Format Output	Produces Markdown, plain text, or HTML with customizable date formats and optional header/footer text.
Dry‑Run Mode	Prints the rendered changelog to stdout without writing a file for quick preview.
Zero‑Dependency Operation	Runs with Python 3.11+ and the standard library; optional GitPython for faster access.

Quick Start

1. Clone the repository:

   git clone https://github.com/yourorg/SuprLogs.git
   

2. Enter the project directory:

   cd SuprLogs
   

3. Install the package in editable mode:

   pip install -e .
   

4. Verify the installation:

   suprlogs --help
   

5. Generate your first changelog:

   suprlogs changelog --since v1.0.0
   

Examples

Basic changelog generation

$ suprlogs changelog --since v1.0.0
## [v1.2.0] - 2024-04-12
### Added
- New user authentication module (feat: add login endpoint)
- Configurable timeout for API calls (feat: introduce timeout setting)
### Fixed
- Resolve crash on empty payload (fix: handle null body)
- Correct typo in validation message (fix: spelling error)

Custom patterns and output file

$ suprlogs changelog --since v0.9.0 --patterns mypatterns.txt --output CHANGELOG.md

Contents of CHANGELOG.md:

## [v1.0.0] - 2024-03-01
### Added
- Introduce REST API endpoints (feat: add api/v1)
### Docs
- Update installation guide (doc: clarify dependencies)

HTML format with header and footer

$ suprlogs changelog --since v1.0.0 --format html --header-text "Release Notes" --footer-text "Generated by SuprLogs"

Output:

Release Notes
<h2>[v1.2.0] - 2024-04-12</h2>
<ul>
<li><strong>Added</strong>: New user authentication module (feat: add login endpoint)</li>
<li><strong>Added</strong>: Configurable timeout for API calls (feat: introduce timeout setting)</li>
<li><strong>Fixed</strong>: Resolve crash on empty payload (fix: handle null body)</li>
<li><strong>Fixed</strong>: Correct typo in validation message (fix: spelling error)</li>
</ul>
Generated by SuprLogs

File Structure

SuprLogs: Auto-Generate Changelogs from Git Commits/
  assets/                  # Project graphics
    infographic.png
  screenshots/             # Example outputs
    M2A-640-cli-help.txt
    M2A-641-markdown-output.txt
  suprlogs/                # Source code
    __init__.py
    cli.py                 # Click CLI entry point
    core/
      __init__.py
      git.py               # Git log fetcher
      classify.py          # Commit classification
      render.py            # Template rendering
    templates/
      default.j2           # Built‑in Keep a Changelog template
      example.j2           # Sample custom template
  tests/                   # Unit tests
    test_cli.py
    test_git.py
    test_classify.py
    test_render.py
  pyproject.toml           # Project metadata and dependencies
  LICENSE                  # MIT license
  README.md                # This file

Tech Stack

Technology	Purpose
Python 3.11+	Core language
Click	CLI argument parsing
GitPython (optional)	Faster Git access (falls back to subprocess)
string.Template (stdlib)	Templating engine
Pytest	Testing framework

Contributing

Fork the repository, create a feature branch, make changes, run tests, submit a pull request.

License

MIT

Author

Matthew Snow -- M2AI | @m2ai-portfolio