{"id":24827915,"url":"https://github.com/onjin/mkchangelog","last_synced_at":"2026-02-27T23:40:53.298Z","repository":{"id":203488264,"uuid":"709717481","full_name":"onjin/mkchangelog","owner":"onjin","description":"The CLI tool to create a changelog for a project from the git log using the conventional commits scheme","archived":false,"fork":false,"pushed_at":"2024-10-29T23:07:56.000Z","size":290,"stargazers_count":5,"open_issues_count":2,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-30T00:39:28.070Z","etag":null,"topics":["cli","conventional-changelog","conventional-commits"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/onjin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-25T08:58:03.000Z","updated_at":"2024-10-29T23:07:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"d7119406-949c-42c0-b518-df321de9b470","html_url":"https://github.com/onjin/mkchangelog","commit_stats":null,"previous_names":["onjin/mkchangelog"],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onjin%2Fmkchangelog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onjin%2Fmkchangelog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onjin%2Fmkchangelog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onjin%2Fmkchangelog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/onjin","download_url":"https://codeload.github.com/onjin/mkchangelog/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":236431072,"owners_count":19147683,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["cli","conventional-changelog","conventional-commits"],"created_at":"2025-01-30T22:23:27.137Z","updated_at":"2025-10-14T01:30:55.474Z","avatar_url":"https://github.com/onjin.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mkchangelog\n\n| Section  | Details |\n|----------|---------|\n| CI/CD   | [![CI - Test](https://github.com/onjin/mkchangelog/actions/workflows/test.yml/badge.svg)](https://github.com/onjin/mkchangelog/actions/workflows/test.yml)                                                                                                                                                                                                                                                                                                                                       |\n| Package | [![PyPI - Version](https://img.shields.io/pypi/v/mkchangelog.svg?logo=pypi\u0026label=PyPI\u0026logoColor=gold)](https://pypi.org/project/mkchangelog/) [![PyPI - Downloads](https://img.shields.io/pypi/dm/mkchangelog.svg?color=blue\u0026label=Downloads\u0026logo=pypi\u0026logoColor=gold)](https://pypi.org/project/mkchangelog/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mkchangelog.svg?logo=python\u0026label=Python\u0026logoColor=gold)](https://pypi.org/project/mkchangelog/)                 |\n| Meta    | [![linting - Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![code style - Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![types - Mypy](https://img.shields.io/badge/types-Mypy-blue.svg)](https://github.com/python/mypy) [![License - MIT](https://img.shields.io/badge/license-MIT-9400d3.svg)](https://spdx.org/licenses/) |\n| License | [![License - MIT](https://img.shields.io/badge/license-MIT-9400d3.svg)](https://spdx.org/licenses/) |\n| Changes | [CHANGELOG.md](CHANGELOG.md) |\n\n\n---\n\nThe CHANGELOG.md generator from git log using the [`conventional commits`](https://www.conventionalcommits.org/en/v1.0.0/) scheme.\n\nExample generated changelog: [CHANGELOG.md](CHANGELOG.md)\n\n**Table of Contents**\n\n- [Installation](#installation)\n- [Usage](#usage)\n- [Configuration](#configuration)\n- [Features](#features)\n- [License](#license)\n\n## Installation\n\n```console\npip install mkchangelog\n```\n\nor use docker image: \n```console\ndocker run -t -v .:/app onjin/mkchangelog generate\n```\n\n## Usage\n\nThe list of versions is taken from list of signed git tags detected by prefix (default `v`, f.e. `v1.3.4`).\n\n### Generate changelog\n\nTo generate changelog for current and all previous versions (signed tags) to CHAGELOG.md (default):\n\n```console\n$ mkchangelog generate       # Creates CHANGELOG.md\n$ mkchangelog g              # Creates CHANGELOG.md\n$ mkchangelog g --stdout     # Prints changelog to stdout\n$ mkchangelog g --help       # Prints help for generate command\n$ git mkc g                  # git mkc alias for mkchangelog\n```\n\n### Generate commit message\n\n```console\n$ mkchangelog commit         # Generates message.txt\n$ mkchangelog c              # Generates message.txt\n$ git mkc c                  # git mkc alias for mkchangelog\n$ git commit -F message.txt  # Use message.txt as commit message\n```\n\n### Bump version\n\nInteractive tool to:\n\n- generate changelog\n- calculate next version from feat/fix/breaking changes commits\n- commit changelog and tag version\n\n```console\n$ mkchangelog bump           # Bumps next version\n$ mkchangelog b              # Bumps next version\n$ mkchangelog b --show-current-version  # Only show current version\n$ mkchangelog b --show-next-version     # Only show next version\n$ git mkc b                  # git mkc alias for mkchangelog\n```\n\n### Manage configuration\n\nYou can change default configuration using `.mkchangelog` (ini format) file in current directory.\n\n```console\n$ mkchangelog settings       # Shows current config as jon\n$ mkchangelog s              # Shows current config as jon\n$ mkchangelog s --generate   # Prints default config ini file\n$ git mkc s                  # git mkc alias for mkchangelog\n```\n\n## Configuration\n\nDefault configuration is:\n\n```ini\n\n[GENERAL]\noutput = CHANGELOG.md                   ; output file\ntemplate = markdown                     ; template to use\ncommit_limit = 100                      ; commits limit per release (version)\nunreleased = False                      ; include unreleased changes (HEAD...last_version)\nunreleased_version = Unreleased         ; title of unreleased changes (f.e. next version v3.0.0)\nhide_empty_releases = False             ; hide releases with no gathered commits\nchangelog_title = Changelog             ; Changelog title\ncommit_types_list = fix,feat            ; list of commit types to include in Changelog\ncommit_type_default_priority = 10       ; default priority of commit type, for Changelog ordering\ntag_prefix = v                          ; versions tag prefix to detect/generate git tags\nignore_revs = 3a3bc...,...              ; ignore certain git revisions durint generating Changelog\n\n[commit_types]                          ; valid commit types (for `--commit-types all`) and their names\nbuild = Build\nchore = Chore\nci = CI\ndev = Dev\ndocs = Docs\nfeat = Features\nfix = Fixes\nperf = Performance\nrefactor = Refactors\nstyle = Style\ntest = Test\ntranslations = Translations\n\n[commit_types_priorities]               ; custom commit types priorities, for Changelog ordering\nfeat = 40\nfix = 30\nrefactor = 20\n```\n\n## Features\n\n### Creates changelog from git log\n\n- the list of releases is created from list of annotated git tags matching configured `tag_prefix`.\n- the unreleased changes are included if `unreleased` is `true`.\n- from git log messages matching configured `commit_types` are parsed and grouped by the type.\n- certain groups (types) are sorted by configured `commit_types_priorities`.\n- only configured `commit_types_list` types are rendered, if not `--commit-types [type,type, | all]` was provided\n- you can also set `ignored_revs` list in `.mkchangelog`, to skip certain git revisions by sha\n\n### Includes additional git commits from text files\n\n- additional commit files (`*.txt`) can be put at `.mkchangelog.d/versions/\u003cversion\u003e/commits/` directory\n\nFor example:\n\n- [v1.0.3/commits](https://github.com/onjin/mkchangelog/blob/master/.mkchangelog.d/versions/v1.0.3/commits/)\n\n### Built-in templates\n\nThe `mkchangelog` includes a few builtin changelog output formats\n\n```console\n$ mkchangelog g --template markdown\n$ mkchangelog g --template rst\n$ mkchangelog g --template json\n```\n\n### Custom `header` and `footer` per version [for built-in templates]\n\nThe `header` and `footer` files are included from files:\n\n- .mkchangelog.d/versions/\u003cversion\u003e/header\n- .mkchangelog.d/versions/\u003cversion\u003e/footer\n\nFor example:\n\n- [v1.0.3/header](https://github.com/onjin/mkchangelog/blob/master/.mkchangelog.d/versions/v1.0.3/header)\n- [v1.0.3/footer](https://github.com/onjin/mkchangelog/blob/master/.mkchangelog.d/versions/v1.0.3/footer)\n\n### Custom [jinja](https://jinja.palletsprojects.com/en/3.1.x/) templates\n\nYou can create your own templates and pass them by `--template` parameter of `mkchangelog generate`\nor set it in `.mkchangelog` configuration file.\n\n**Using configuration file**\n\n```dosini\n[GENERAL]\n...\n# put `custom_template.jinja` in `.mkchangelog.d/templates/\ntemplate = custom_template.jinja\n\n# or specify full path to template\ntemplate = ./path/to/template.jinja\n...\n```\n\n**Using `--template` parameter\\***\n\n```console\n# put `custom_template.jinja` in `.mkchangelog.d/templates/\n$ mkchangelog g --template custom_template.jinja\n\n# or specify full path to template\n$ mkchangelog g --template ./path/to/template.jinja\n```\n\nRefer to built-in templates for examples:\n\n- [markdown.jinja2](https://github.com/onjin/mkchangelog/blob/master/mkchangelog/templates/markdown.jinja2)\n- [rst.jinja2](https://github.com/onjin/mkchangelog/blob/master/mkchangelog/templates/rst.jinja2)\n\n### Template filters\n\nApart from builtin jinja2 filter there are additional custom filters:\n\n- `underline` - f.e. `{{ changelog.title | underline('=') }}`\n- `regex_replace` - f.e. `{{ \"line with #12 issue ref\" | regex_replace(\"#(\\d+)\", \"#ISSUE-\\\\1\") }}`\n\nYou can create and register your own filters using **.mkchangelog.d/hooks.py** file.\n\nExample implementation of hooks:\n\n- https://github.com/onjin/mkchangelog/blob/master/.mkchangelog.d/hooks.py\n\n### Your own commit types\n\nThe `commit_types` can be fully customized by `.mkchangelog` file.\n\n```ini\n[GENERAL]\ncommit_types_list = awesome\nhide_empty_releases = True\n\n[commit_types]\nawesome = Best change\nsad = Had to write it\nnot_sure = Works but why?\n\n[commit_types_priorities]\nawesome = 40\nsad = 30\nnot_sure = 20\n\n```\n\n```console\n$ mkchangelog g --commit_types all\n$ mdless CHANGELOG.md\n```\n\n![image](https://github.com/onjin/mkchangelog/assets/44516/33f9b6dd-2860-437e-98be-d3a2e1819223)\n\n### Plugins / hooks system\n\nYou can use hooks system to extend mkchangelog functionality.\nAll hooks are loaded from `.mkchangelog.d/hooks.py` file which must be a valid python module.\n\nYou can check the specification for available hooks at [hookspecs.py](https://github.com/onjin/mkchangelog/blob/master/mkchangelog/hookspecs.py) file.\nThe mkchangelog built-in hooks are implemented at [lib.py](https://github.com/onjin/mkchangelog/blob/master/mkchangelog/lib.py) file.\n\n**Available hooks**:\n\n- provide_template_filters - returns dictionary of jinja2 filters,\n- provide_changelog_loglines_filter - returns functions which filters list of `LogLine` - you can use it to filter out f.e. some scopes\n\n**Example .mkchangelog.d/hooks.py**\n\n```python\n\nfrom __future__ import annotations\n\nimport random\nfrom typing import Any, Callable, Dict, List\n\nfrom mkchangelog.config import Settings\nfrom mkchangelog.lib import hookimpl\n\n\ndef fancylize(s):\n    return \"\".join([c.lower() if random.randint(0, 1) else c.upper() for c in s])\n\n\n@hookimpl\ndef provide_template_filters(settings: Settings) -\u003e Dict[str, Callable[[Any], str]]:  # noqa\n    \"\"\"Add 'fancylize' jinja2 template filter\"\"\"\n    return {\"fancylize\": fancylize}\n\n\n@hookimpl\ndef provide_changelog_loglines_filter(settings: Settings) -\u003e Callable[[List[LogLine]], List[LogLine]]:\n    \"\"\"Hide lines with scope 'hidden_scope'\"\"\"\n    return lambda loglines: [line for line in loglines if line.scope != \"hidden_scope\"]\n\n```\n\n## Contributing\n\nInstall `pre-commit`\n\n```python\npip install pre-commit\npre-commit install\n```\n\n### Run tests\n\n```console\nhatch run all:test\n```\n\n### Linting\n\n```console\nhatch run lint:all\n```\n\n## License\n\n`mkchangelog` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonjin%2Fmkchangelog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonjin%2Fmkchangelog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonjin%2Fmkchangelog/lists"}