Skip to main content

Generate changelog from Git commits.

Project description

Generate changelog from Git commits.

PyPI Version Supported Python versions Build Status GPL-2.0-only OR LGPL-2.1-or-later Coverage


  • Python 3.6, 3.7 and 3.8


Documentation is available on Read the Docs.


Latest stable version on PyPI:

pip install matyan


Basic usage

See Basic concepts section to get impression on possible commit methodology and assumptions taken.

Generate changelog:


Generate changelog skipping orphaned commits:

In some cases you would only want to show what has been done with tickets and skip all non-ticket related commits.

generate-changelog --no-other

Generate changelog between two releases:

In other cases you would want to show what has been done since last release. The following example would generate changelog since version 0.0.1 to version 0.0.3.

generate-changelog 0.0.1..0.0.3

Generate changelog between two branches:

Sometimes you just need to show the changes made on acceptance since last production release. The following example would generate changelog with changes that are on acceptance branch and not yet in master.

generate-changelog master..acceptance

Generate changelog with releases info shown

generate-changelog --show-releases

Generate changelog between releases with releases info shown

generate-changelog 0.0.1..0.0.3 --show-releases

Generate changelog between branches with releases info shown

generate-changelog --show-releases

Generate changelog for the latest release with releases info shown

generate-changelog --latest-release --show-releases

Generate changelog with headings only (no commit messages) and releases info shown

generate-changelog --headings-only --show-releases

Generate changelog between two branches, show unreleased changes only:

generate-changelog master..acceptance --show-releases --unreleased-only


The following renderers are implemented:

  • Markdown
  • RestructuredText
  • Historical Markdown (for compatibility with matyan versions prior to 0.4).


generate-changelog --show-releases --renderer=markdown


generate-changelog --show-releases --renderer=rest

Historical Markdown

generate-changelog --show-releases --renderer=historical-markdown

Jira integration

It’s possible to fetch ticket title and description from Jira. In order for it to work, you should provide a fetch-title and fetch-description arguments.

The following needs to be added to your .matyan.ini:


In addition to that, you should put valid Jira credentials into your global .matyan.ini configuration file.

Command to run:

generate-changelog --show-releases --fetch-title --fetch-description

Have in mind, that matyan shall be installed with jira option.

pip install matyan[jira]

Alternatively, make sure atlassian-python-api is installed.

pip install atlassian-python-api


See the output directory for examples.

Additionally see the Jupyter notebook examples.


In order to customize names and texts, add a .matyan.ini in your project directory, from which you will be running the generate-changelog command.

Sample configuration:

feature: Feature
bugfix: Bugfix
hotfix: Hotfix
deprecation: Deprecation

other: Other

unreleased: Unreleased

exact: more
       clean up
       code comments
       more on docs
       more on
prefix: more on
        continue on

Note, that placing .matyan.ini into the home root will make that configuration global for all projects. That however could be handy, since local .matyan.ini files simply extend the global ones. For example, you could use global configuration for storing Jira credentials.


Note, however, that sections are copied over entirely.

Tips and tricks

Write to file

generate-changelog --show-releases 2>&1 | tee

Create initial config file



Simply type:


Or use tox:


Or use tox to check specific env:

tox -e py38


Sometimes checking logs could be handy. Matyan logs are stored in the directory, from which you are running the generate-changelog (or any other Matyan) command.

Update your .matyan.ini configuration in the following way:

tail -f /path/to/your/project/matyan.log

If you want to modify current logging, use MATYAN_LOGGING_CONFIG environment variable.

Default configuration:

    'version': 1,
    'disable_existing_loggers': False,
    'root': {
        'level': 'WARNING',
        'handlers': ['file'],
    'formatters': {
        'verbose': {
            'format': '{levelname} {asctime} {module} {process:d} {thread:d} '
            'style': '{',
        'simple': {
            'format': '{levelname} {message}',
            'style': '{',
    'handlers': {
        'console': {
            'level': 'WARNING',
            'class': 'logging.StreamHandler',
            'formatter': 'simple'
        'file': {
            'level': 'WARNING',
            'class': 'logging.handlers.RotatingFileHandler',
            'filename': os.path.join(os.getcwd(), "matyan.log"),
            'maxBytes': 1048576,
            'backupCount': 99,
            'formatter': 'verbose',
    'loggers': {
        'matyan': {
            'handlers': ['file'],
            'propagate': True,

Writing documentation

Keep the following hierarchy.









GPL-2.0-only OR LGPL-2.1-or-later


For any issues contact me at the e-mail given in the Author section.


Artur Barseghyan <>

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

matyan-0.4.7.tar.gz (52.2 kB view hashes)

Uploaded source

Built Distribution

matyan-0.4.7-py2.py3-none-any.whl (52.1 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page