# Git Changelog Maestro
**Git Changelog Maestro** is a modern CLI tool that automatically generates changelogs from your Git commit history. It supports **Conventional Commits**, multiple output styles (Markdown, JSON, YAML), custom templates, and integrates perfectly with **CI/CD pipelines**. Built for **developers, teams, and open-source maintainers** who want clean, automated changelogs with minimal effort.
[](https://badge.fury.io/py/git-changelog-maestro)
[](https://pypi.org/project/git-changelog-maestro/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/petherldev/git-changelog-maestro/actions)
[](https://codecov.io/gh/petherldev/git-changelog-maestro)
## Features
| Feature | Description |
| ----------------------- | ----------------------------------------------------------------------- |
| Conventional Commits | Parses Git commit messages using the Conventional Commits specification |
| Multi-format Output | Outputs changelogs in Markdown, JSON, or YAML |
| Custom Templates | Use or create templates with Jinja2 |
| Semantic Versioning | Detects versions automatically from Git tags |
| Rich CLI | Colorful, structured CLI output using Rich |
| Fast & Modern | Built with modern Python and fully tested |
| Configurable | Easily customize behavior via `pyproject.toml` |
| CI/CD Ready | Seamless integration in release pipelines |
## Quick Start
### Installation
```bash
pip install git-changelog-maestro
```
### Basic Usage
```bash
changelog-maestro
```
This creates a `CHANGELOG.md` file in your current directory with all changes from the full Git history.
> \[!TIP]
> Use `--since <tag>` to generate changelogs from a specific point in time.
### Advanced Usage
```bash
# Generate changelog from specific tag
changelog-maestro --since v1.0.0
# Generate changelog between two tags
changelog-maestro --since v1.0.0 --until v2.0.0
# Output in JSON format
changelog-maestro --style json --output changelog.json
# Use custom template
changelog-maestro --template my-template.md.j2
# Exclude merge commits and specific patterns
changelog-maestro --no-merges --exclude "chore" --exclude "docs"
# Verbose output with preview
changelog-maestro --verbose
```
## CLI Reference
```
changelog-maestro [OPTIONS] COMMAND [ARGS]...
Options:
--repo-path PATH Git repository path [default: current]
--output FILE Output file [default: CHANGELOG.md]
--template PATH Custom template file
--since TAG Generate from specific tag
--until TAG Generate until specific tag
--version-prefix TEXT Version prefix [default: v]
--style TEXT Output style [default: markdown]
--sections TEXT Custom sections to include
--exclude TEXT Patterns to exclude
--no-merges Exclude merge commits
--verbose Increase output verbosity
Commands:
generate Generate changelog from Git commit history
validate Validate commit messages against Conventional Commits
init Initialize changelog configuration
```
## Configuration
You can configure Git Changelog Maestro via `pyproject.toml`.
```toml
[tool.changelog-maestro]
output_file = "CHANGELOG.md"
version_prefix = "v"
include_merges = false
[tool.changelog-maestro.commit_types]
feat = "Features"
fix = "Bug Fixes"
docs = "Documentation"
style = "Styles"
refactor = "Code Refactoring"
perf = "Performance Improvements"
test = "Tests"
build = "Builds"
ci = "Continuous Integration"
chore = "Chores"
revert = "Reverts"
breaking_change_indicators = ["BREAKING CHANGE", "BREAKING-CHANGE"]
exclude_patterns = ["wip", "temp"]
```
Initialize configuration interactively:
```bash
changelog-maestro init
```
## Conventional Commits
This tool supports the [Conventional Commits](https://www.conventionalcommits.org/) specification.
```
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
```
### Examples
```bash
# Feature
git commit -m "feat: add user authentication"
# Bug fix
git commit -m "fix: resolve login validation issue"
# Breaking change
git commit -m "feat!: change API response format"
# With scope
git commit -m "feat(auth): add OAuth2 support"
# With body and footer
git commit -m "feat: add user profiles
Allow users to create and customize their profiles
with avatar upload and bio information.
Closes #123"
```
## Custom Templates
Use custom templates written in Jinja2 for changelog formatting.
```jinja2
# custom-template.md.j2
# My Project Changelog
{% for entry in entries %}
## Version {{ entry.version }} ({{ entry.date | format_date }})
{% if entry.breaking_changes %}
### 💥 Breaking Changes
{% for commit in entry.breaking_changes %}
- {{ commit.description }}
{% endfor %}
{% endif %}
{% for section_name, commits in entry.sections.items() %}
### {{ section_name }}
{% for commit in commits %}
- {{ commit.description }}{% if commit.scope %} ({{ commit.scope }}){% endif %}
{% endfor %}
{% endfor %}
{% endfor %}
```
Run with:
```bash
changelog-maestro --template custom-template.md.j2
```
## Validation
```bash
changelog-maestro validate
```
> \[!CAUTION]
> This will scan your Git history and report any commits that do not comply with the Conventional Commits format.
## CI/CD Integration
### GitHub Actions
```yaml
name: Generate Changelog
on:
push:
tags:
- 'v*'
jobs:
changelog:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
- name: Install changelog-maestro
run: pip install git-changelog-maestro
- name: Generate changelog
run: changelog-maestro --since $(git describe --tags --abbrev=0 HEAD^)
- name: Commit changelog
run: |
git config user.email "github-actions[bot]@users.noreply.github.com"
git config user.name "github-actions[bot]"
git add CHANGELOG.md
git commit -m "docs: update changelog for ${{ github.ref_name }}" || exit 0
git push
```
## Development
### Setup
```bash
git clone https://github.com/petherldev/git-changelog-maestro.git
cd git-changelog-maestro
pip install -e ".[dev]"
```
### Testing
```bash
pytest # Run tests
pytest --cov=changelog_maestro # With coverage
pytest -v # Verbose output
pytest tests/test_parser.py # Single file
```
### Code Quality
```bash
black changelog_maestro tests # Format
isort changelog_maestro tests # Sort imports
flake8 changelog_maestro tests # Lint
mypy changelog_maestro # Type check
```
### Pre-commit
```bash
pre-commit install
pre-commit run --all-files
```
## Output Examples
### Markdown
```markdown
## [1.2.0] - 2023-12-01
### ⚠ BREAKING CHANGES
### Bug Fixes
- correct scope formatting in changelog template `(template)`
### Features
- add GitHub Actions workflow to auto-generate changelog on new tag `(ci)`
Introduces changelog.yml which triggers on version tags (v*),
installs git-changelog-maestro, generates CHANGELOG.md, and commits it back to the repository.
```
### JSON
```json
{
"changelog": [
{
"version": "1.2.0",
"date": "2023-12-01T00:00:00",
"sections": {
"Features": [
{
"type": "feat",
"scope": "auth",
"description": "add OAuth2 authentication support",
"body": null,
"is_breaking": false
}
]
},
"breaking_changes": []
}
],
"generated_at": "2023-12-01T10:30:00"
}
```
## Contributing
> \[!NOTE]
> Please open an issue before starting major work.
- [x] Fork the repo
- [x] Create a branch (`git checkout -b feat/your-feature`)
- [x] Code and add tests
- [x] Ensure all tests pass
- [x] Commit changes (`git commit -m "feat: your feature"`)
- [x] Push (`git push origin feat/your-feature`)
- [x] Open a PR 🎉
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file.
## Acknowledgments
* [Conventional Commits](https://www.conventionalcommits.org/)
* [Keep a Changelog](https://keepachangelog.com/)
* [Semantic Versioning](https://semver.org/)
* [Rich](https://github.com/Textualize/rich)
* [Click](https://click.palletsprojects.com/)
## Support
> \[!TIP]
> Check existing issues or create a new one if you need help.
* [Search Issues](https://github.com/petherldev/git-changelog-maestro/issues)
* [Open Issue](https://github.com/petherldev/git-changelog-maestro/issues/new)
Made with ❤️ by [HErl](https://github.com/petherldev)
Raw data
{
"_id": null,
"home_page": null,
"name": "git-changelog-maestro",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "changelog, cli, conventional-commits, git, semantic-versioning",
"author": null,
"author_email": "petherldev <petherl@protonmail.com>",
"download_url": "https://files.pythonhosted.org/packages/4f/7e/2278b2c6d0300ba8f8e61b9cc7733cfa65c00fe64debd22b6aae146b9039/git_changelog_maestro-0.1.2.tar.gz",
"platform": null,
"description": "# Git Changelog Maestro\n\n**Git Changelog Maestro** is a modern CLI tool that automatically generates changelogs from your Git commit history. It supports **Conventional Commits**, multiple output styles (Markdown, JSON, YAML), custom templates, and integrates perfectly with **CI/CD pipelines**. Built for **developers, teams, and open-source maintainers** who want clean, automated changelogs with minimal effort.\n\n[](https://badge.fury.io/py/git-changelog-maestro)\n[](https://pypi.org/project/git-changelog-maestro/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/petherldev/git-changelog-maestro/actions)\n[](https://codecov.io/gh/petherldev/git-changelog-maestro)\n\n\n## Features\n\n| Feature | Description |\n| ----------------------- | ----------------------------------------------------------------------- |\n| Conventional Commits | Parses Git commit messages using the Conventional Commits specification |\n| Multi-format Output | Outputs changelogs in Markdown, JSON, or YAML |\n| Custom Templates | Use or create templates with Jinja2 |\n| Semantic Versioning | Detects versions automatically from Git tags |\n| Rich CLI | Colorful, structured CLI output using Rich |\n| Fast & Modern | Built with modern Python and fully tested |\n| Configurable | Easily customize behavior via `pyproject.toml` |\n| CI/CD Ready | Seamless integration in release pipelines |\n\n\n## Quick Start\n\n### Installation\n\n```bash\npip install git-changelog-maestro\n```\n\n### Basic Usage\n\n```bash\nchangelog-maestro\n```\n\nThis creates a `CHANGELOG.md` file in your current directory with all changes from the full Git history.\n\n> \\[!TIP]\n> Use `--since <tag>` to generate changelogs from a specific point in time.\n\n\n### Advanced Usage\n\n```bash\n# Generate changelog from specific tag\nchangelog-maestro --since v1.0.0\n\n# Generate changelog between two tags\nchangelog-maestro --since v1.0.0 --until v2.0.0\n\n# Output in JSON format\nchangelog-maestro --style json --output changelog.json\n\n# Use custom template\nchangelog-maestro --template my-template.md.j2\n\n# Exclude merge commits and specific patterns\nchangelog-maestro --no-merges --exclude \"chore\" --exclude \"docs\"\n\n# Verbose output with preview\nchangelog-maestro --verbose\n```\n\n\n## CLI Reference\n\n```\nchangelog-maestro [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --repo-path PATH Git repository path [default: current]\n --output FILE Output file [default: CHANGELOG.md]\n --template PATH Custom template file\n --since TAG Generate from specific tag\n --until TAG Generate until specific tag\n --version-prefix TEXT Version prefix [default: v]\n --style TEXT Output style [default: markdown]\n --sections TEXT Custom sections to include\n --exclude TEXT Patterns to exclude\n --no-merges Exclude merge commits\n --verbose Increase output verbosity\n\nCommands:\n generate Generate changelog from Git commit history\n validate Validate commit messages against Conventional Commits\n init Initialize changelog configuration\n```\n\n\n## Configuration\n\nYou can configure Git Changelog Maestro via `pyproject.toml`.\n\n```toml\n[tool.changelog-maestro]\noutput_file = \"CHANGELOG.md\"\nversion_prefix = \"v\"\ninclude_merges = false\n\n[tool.changelog-maestro.commit_types]\nfeat = \"Features\"\nfix = \"Bug Fixes\"\ndocs = \"Documentation\"\nstyle = \"Styles\"\nrefactor = \"Code Refactoring\"\nperf = \"Performance Improvements\"\ntest = \"Tests\"\nbuild = \"Builds\"\nci = \"Continuous Integration\"\nchore = \"Chores\"\nrevert = \"Reverts\"\n\nbreaking_change_indicators = [\"BREAKING CHANGE\", \"BREAKING-CHANGE\"]\nexclude_patterns = [\"wip\", \"temp\"]\n```\n\nInitialize configuration interactively:\n\n```bash\nchangelog-maestro init\n```\n\n\n## Conventional Commits\n\nThis tool supports the [Conventional Commits](https://www.conventionalcommits.org/) specification.\n\n```\n<type>[optional scope]: <description>\n\n[optional body]\n\n[optional footer(s)]\n```\n\n### Examples\n\n```bash\n# Feature\ngit commit -m \"feat: add user authentication\"\n\n# Bug fix\ngit commit -m \"fix: resolve login validation issue\"\n\n# Breaking change\ngit commit -m \"feat!: change API response format\"\n\n# With scope\ngit commit -m \"feat(auth): add OAuth2 support\"\n\n# With body and footer\ngit commit -m \"feat: add user profiles\n\nAllow users to create and customize their profiles\nwith avatar upload and bio information.\n\nCloses #123\"\n```\n\n\n## Custom Templates\n\nUse custom templates written in Jinja2 for changelog formatting.\n\n```jinja2\n# custom-template.md.j2\n# My Project Changelog\n\n{% for entry in entries %}\n## Version {{ entry.version }} ({{ entry.date | format_date }})\n\n{% if entry.breaking_changes %}\n### \ud83d\udca5 Breaking Changes\n{% for commit in entry.breaking_changes %}\n- {{ commit.description }}\n{% endfor %}\n{% endif %}\n\n{% for section_name, commits in entry.sections.items() %}\n### {{ section_name }}\n{% for commit in commits %}\n- {{ commit.description }}{% if commit.scope %} ({{ commit.scope }}){% endif %}\n{% endfor %}\n{% endfor %}\n{% endfor %}\n```\n\nRun with:\n\n```bash\nchangelog-maestro --template custom-template.md.j2\n```\n\n\n## Validation\n\n```bash\nchangelog-maestro validate\n```\n\n> \\[!CAUTION]\n> This will scan your Git history and report any commits that do not comply with the Conventional Commits format.\n\n\n## CI/CD Integration\n\n### GitHub Actions\n\n```yaml\nname: Generate Changelog\n\non:\n push:\n tags:\n - 'v*'\n\njobs:\n changelog:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n with:\n fetch-depth: 0\n \n - name: Set up Python\n uses: actions/setup-python@v4\n with:\n python-version: '3.11'\n \n - name: Install changelog-maestro\n run: pip install git-changelog-maestro\n \n - name: Generate changelog\n run: changelog-maestro --since $(git describe --tags --abbrev=0 HEAD^)\n \n - name: Commit changelog\n run: |\n git config user.email \"github-actions[bot]@users.noreply.github.com\"\n git config user.name \"github-actions[bot]\"\n git add CHANGELOG.md\n git commit -m \"docs: update changelog for ${{ github.ref_name }}\" || exit 0\n git push\n```\n\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/petherldev/git-changelog-maestro.git\ncd git-changelog-maestro\npip install -e \".[dev]\"\n```\n\n### Testing\n\n```bash\npytest # Run tests\npytest --cov=changelog_maestro # With coverage\npytest -v # Verbose output\npytest tests/test_parser.py # Single file\n```\n\n### Code Quality\n\n```bash\nblack changelog_maestro tests # Format\nisort changelog_maestro tests # Sort imports\nflake8 changelog_maestro tests # Lint\nmypy changelog_maestro # Type check\n```\n\n### Pre-commit\n\n```bash\npre-commit install\npre-commit run --all-files\n```\n\n\n## Output Examples\n\n### Markdown\n\n```markdown\n## [1.2.0] - 2023-12-01\n\n### \u26a0 BREAKING CHANGES\n\n### Bug Fixes\n\n\n- correct scope formatting in changelog template `(template)`\n\n### Features\n\n\n- add GitHub Actions workflow to auto-generate changelog on new tag `(ci)`\n\n\n Introduces changelog.yml which triggers on version tags (v*), \n\n installs git-changelog-maestro, generates CHANGELOG.md, and commits it back to the repository.\n```\n\n### JSON\n\n```json\n{\n \"changelog\": [\n {\n \"version\": \"1.2.0\",\n \"date\": \"2023-12-01T00:00:00\",\n \"sections\": {\n \"Features\": [\n {\n \"type\": \"feat\",\n \"scope\": \"auth\",\n \"description\": \"add OAuth2 authentication support\",\n \"body\": null,\n \"is_breaking\": false\n }\n ]\n },\n \"breaking_changes\": []\n }\n ],\n \"generated_at\": \"2023-12-01T10:30:00\"\n}\n```\n\n\n## Contributing\n\n> \\[!NOTE]\n> Please open an issue before starting major work.\n\n- [x] Fork the repo\n- [x] Create a branch (`git checkout -b feat/your-feature`)\n- [x] Code and add tests\n- [x] Ensure all tests pass\n- [x] Commit changes (`git commit -m \"feat: your feature\"`)\n- [x] Push (`git push origin feat/your-feature`)\n- [x] Open a PR \ud83c\udf89\n\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file.\n\n\n## Acknowledgments\n\n* [Conventional Commits](https://www.conventionalcommits.org/)\n* [Keep a Changelog](https://keepachangelog.com/)\n* [Semantic Versioning](https://semver.org/)\n* [Rich](https://github.com/Textualize/rich)\n* [Click](https://click.palletsprojects.com/)\n\n\n## Support\n\n> \\[!TIP]\n> Check existing issues or create a new one if you need help.\n\n* [Search Issues](https://github.com/petherldev/git-changelog-maestro/issues)\n* [Open Issue](https://github.com/petherldev/git-changelog-maestro/issues/new)\n\n\nMade with \u2764\ufe0f by [HErl](https://github.com/petherldev)\n",
"bugtrack_url": null,
"license": null,
"summary": "Generate elegant changelogs from Git commit history using Conventional Commits",
"version": "0.1.2",
"project_urls": {
"Changelog": "https://github.com/petherldev/git-changelog-maestro/blob/main/CHANGELOG.md",
"Homepage": "https://github.com/petherldev/git-changelog-maestro",
"Issues": "https://github.com/petherldev/git-changelog-maestro/issues",
"Repository": "https://github.com/petherldev/git-changelog-maestro"
},
"split_keywords": [
"changelog",
" cli",
" conventional-commits",
" git",
" semantic-versioning"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2a0c5b678d3a0ee8da603097f7ec7aca2dddb8b40af890f1d6d28963e620be71",
"md5": "83af5fb645362fbcd5b3a8e3d912c536",
"sha256": "def05ee1bdd3decc8fae515dc581b6836b193fdb2f417bd3155b50e8846ed769"
},
"downloads": -1,
"filename": "git_changelog_maestro-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "83af5fb645362fbcd5b3a8e3d912c536",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 20700,
"upload_time": "2025-08-08T00:39:58",
"upload_time_iso_8601": "2025-08-08T00:39:58.698854Z",
"url": "https://files.pythonhosted.org/packages/2a/0c/5b678d3a0ee8da603097f7ec7aca2dddb8b40af890f1d6d28963e620be71/git_changelog_maestro-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4f7e2278b2c6d0300ba8f8e61b9cc7733cfa65c00fe64debd22b6aae146b9039",
"md5": "d5d22aa5d4d208f4cd14fca7783543da",
"sha256": "7d7b150f65a04381821295d1f72527883337b443e3d45f7edf2910a9a40b338a"
},
"downloads": -1,
"filename": "git_changelog_maestro-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "d5d22aa5d4d208f4cd14fca7783543da",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 24354,
"upload_time": "2025-08-08T00:39:59",
"upload_time_iso_8601": "2025-08-08T00:39:59.839397Z",
"url": "https://files.pythonhosted.org/packages/4f/7e/2278b2c6d0300ba8f8e61b9cc7733cfa65c00fe64debd22b6aae146b9039/git_changelog_maestro-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-08 00:39:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "petherldev",
"github_project": "git-changelog-maestro",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "git-changelog-maestro"
}
JSON
