Generate changelog from git log with convencional commits.
Project description
mkchangelog
The CHANGELOG.md generator from git log using the conventional commits
scheme.
Example generated changelog: CHANGELOG.md
Table of Contents
Installation
pip install mkchangelog
Usage
The list of versions is taken from list of signed git tags detected by prefix (default v
, f.e. v1.3.4
).
Generate changelog
To generate changelog for current and all previous versions (signed tags) to CHAGELOG.md (default):
$ mkchangelog generate # Creates CHANGELOG.md
$ mkchangelog g # Creates CHANGELOG.md
$ mkchangelog g --stdout # Prints changelog to stdout
$ mkchangelog g --help # Prints help for generate command
$ git mkc g # git mkc alias for mkchangelog
Generate commit message
$ mkchangelog commit # Generates message.txt
$ mkchangelog c # Generates message.txt
$ git mkc c # git mkc alias for mkchangelog
$ git commit -F message.txt # Use message.txt as commit message
Bump version
Interactive tool to:
- generate changelog
- calculate next version from feat/fix/breaking changes commits
- commit changelog and tag version
$ mkchangelog bump # Bumps next version
$ mkchangelog b # Bumps next version
$ mkchangelog b --show-current-version # Only show current version
$ mkchangelog b --show-next-version # Only show next version
$ git mkc b # git mkc alias for mkchangelog
Manage configuration
You can change default configuration using .mkchangelog
(ini format) file in current directory.
$ mkchangelog settings # Shows current config as jon
$ mkchangelog s # Shows current config as jon
$ mkchangelog s --generate # Prints default config ini file
$ git mkc s # git mkc alias for mkchangelog
Configuration
Default configuration is:
[GENERAL]
output = CHANGELOG.md ; output file
template = markdown ; template to use
commit_limit = 100 ; commits limit per release (version)
unreleased = False ; include unreleased changes (HEAD...last_version)
unreleased_version = Unreleased ; title of unreleased changes (f.e. next version v3.0.0)
hide_empty_releases = False ; hide releases with no gathered commits
changelog_title = Changelog ; Changelog title
commit_types_list = fix,feat ; list of commit types to include in Changelog
commit_type_default_priority = 10 ; default priority of commit type, for Changelog ordering
tag_prefix = v ; versions tag prefix to detect/generate git tags
ignore_revs = 3a3bc...,... ; ignore certain git revisions durint generating Changelog
[commit_types] ; valid commit types (for `--commit-types all`) and their names
build = Build
chore = Chore
ci = CI
dev = Dev
docs = Docs
feat = Features
fix = Fixes
perf = Performance
refactor = Refactors
style = Style
test = Test
translations = Translations
[commit_types_priorities] ; custom commit types priorities, for Changelog ordering
feat = 40
fix = 30
refactor = 20
Features
Creates changelog from git log
- the list of releases is created from list of annotated git tags matching configured
tag_prefix
. - the unreleased changes are included if
unreleased
istrue
. - from git log messages matching configured
commit_types
are parsed and grouped by the type. - certain groups (types) are sorted by configured
commit_types_priorities
. - only configured
commit_types_list
types are rendered, if not--commit-types [type,type, | all]
was provided - you can also set
ignored_revs
list in.mkchangelog
, to skip certain git revisions by sha
Includes additional git commits from text files
- additional commit files (
*.txt
) can be put at.mkchangelog.d/versions/<version>/commits/
directory
For example:
Built-in templates
The mkchangelog
includes a few builtin changelog output formats
$ mkchangelog g --template markdown
$ mkchangelog g --template rst
$ mkchangelog g --template json
Custom header
and footer
per version [for built-in templates]
The header
and footer
files are included from files:
- .mkchangelog.d/versions//header
- .mkchangelog.d/versions//footer
For example:
Custom jinja templates
You can create your own templates and pass them by --template
parameter of mkchangelog generate
or set it in .mkchangelog
configuration file.
Using configuration file
[GENERAL]
...
# put `custom_template.jinja` in `.mkchangelog.d/templates/
template = custom_template.jinja
# or specify full path to template
template = ./path/to/template.jinja
...
Using --template
parameter*
# put `custom_template.jinja` in `.mkchangelog.d/templates/
$ mkchangelog g --template custom_template.jinja
# or specify full path to template
$ mkchangelog g --template ./path/to/template.jinja
Refer to built-in templates for examples:
Template filters
Apart from builtin jinja2 filter there are additional custom filters:
underline
- f.e.{{ changelog.title | underline('=') }}
regex_replace
- f.e.{{ "line with #12 issue ref" | regex_replace("#(\d+)", "#ISSUE-\\1") }}
You can create and register your own filters using .mkchangelog.d/hooks.py file.
Example implementation of hooks:
Your own commit types
The commit_types
can be fully customized by .mkchangelog
file.
[GENERAL]
commit_types_list = awesome
hide_empty_releases = True
[commit_types]
awesome = Best change
sad = Had to write it
not_sure = Works but why?
[commit_types_priorities]
awesome = 40
sad = 30
not_sure = 20
$ mkchangelog g --commit_types all
$ mdless CHANGELOG.md
Plugins / hooks system
You can use hooks system to extend mkchangelog functionality.
All hooks are loaded from .mkchangelog.d/hooks.py
file which must be a valid python module.
You can check the specification for available hooks at hookspecs.py file. The mkchangelog built-in hooks are implemented at lib.py file.
Available hooks:
- provide_template_filters - returns dictionary of jinja2 filters,
- provide_changelog_loglines_filter - returns functions which filters list of
LogLine
- you can use it to filter out f.e. some scopes
Example .mkchangelog.d/hooks.py
from __future__ import annotations
import random
from typing import Any, Callable, Dict, List
from mkchangelog.config import Settings
from mkchangelog.lib import hookimpl
def fancylize(s):
return "".join([c.lower() if random.randint(0, 1) else c.upper() for c in s])
@hookimpl
def provide_template_filters(settings: Settings) -> Dict[str, Callable[[Any], str]]: # noqa
"""Add 'fancylize' jinja2 template filter"""
return {"fancylize": fancylize}
@hookimpl
def provide_changelog_loglines_filter(settings: Settings) -> Callable[[List[LogLine]], List[LogLine]]:
"""Hide lines with scope 'hidden_scope'"""
return lambda loglines: [line for line in loglines if line.scope != "hidden_scope"]
Contributing
Install pre-commit
pip install pre-commit
pre-commit install
Run tests
hatch run all:test
Linting
hatch run lint:all
License
mkchangelog
is distributed under the terms of the MIT license.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file mkchangelog-2.6.0.tar.gz
.
File metadata
- Download URL: mkchangelog-2.6.0.tar.gz
- Upload date:
- Size: 30.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.11.9
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9f25791a65562a717889cdddf578e6a91a7f11d9617401279f43932e550c620c |
|
MD5 | 3c5b8167771325004a06933f9f7d38d7 |
|
BLAKE2b-256 | e7683e243b1e1176513409fcbbe6a0f35003c3b42b2e9808f0ea8e01522148a9 |
File details
Details for the file mkchangelog-2.6.0-py3-none-any.whl
.
File metadata
- Download URL: mkchangelog-2.6.0-py3-none-any.whl
- Upload date:
- Size: 27.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.11.9
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | a0b7b09c24ec8dcb34764af881875afb155a8ff312c46c44d14c4f63ac7c9bb2 |
|
MD5 | 535dcc57014bf6f95dd3c8d6805e1184 |
|
BLAKE2b-256 | 626e20daca6a61830e8b3bd2b3bf9046cd8b4c0fcdd3fd60b6efc4b11446a2ce |