Skip to content

CLI reference¤

git-changelog¤

Automatic Changelog generator using Jinja2 templates.

This tool parses your commit messages to extract useful data that is then rendered using Jinja2 templates, for example to a changelog file formatted in Markdown.

Each Git tag will be treated as a version of your project. Each version contains a set of commits, and will be an entry in your changelog. Commits in each version will be grouped by sections, depending on the commit convention you follow.

Conventions¤

Basic¤

Default sections:

add: Added
fix: Fixed
change: Changed
remove: Removed

Additional sections:

merge: Merged
doc: Documented

Angular¤

Default sections:

feat: Features
fix: Bug Fixes
revert: Reverts
ref, refactor: Code Refactoring
perf: Performance Improvements

Additional sections:

build: Build
chore: Chore
ci: Continuous Integration
deps: Dependencies
doc, docs: Docs
style: Style
test, tests: Tests

ConventionalCommit¤

Default sections:

feat: Features
fix: Bug Fixes
revert: Reverts
ref, refactor: Code Refactoring
perf: Performance Improvements

Additional sections:

build: Build
chore: Chore
ci: Continuous Integration
deps: Dependencies
doc, docs: Docs
style: Style
test, tests: Tests

Positional Arguments¤

`repository`¤

REPOSITORY: The repository path, relative or absolute. Default: current working directory.

Options¤

`bump`¤

-B, --bump VERSION: Specify the bump from latest version for the set of unreleased commits. Can be one of auto, major, minor, patch or a valid SemVer version (eg. 1.2.3). For both SemVer and PEP 440 versioning schemes (see -n), auto will bump the major number if a commit contains breaking changes (or the minor number for 0.x versions, see -Z), else the minor number if there are new features, else the patch number. Default: unset (false).

`bump_latest`¤

-b, --bump-latest: Deprecated, use --bump=auto instead. Guess the new latest version by bumping the previous one based on the set of unreleased commits. For example, if a commit contains breaking changes, bump the major number (or the minor number for 0.x versions). Else if there are new features, bump the minor number. Else just bump the patch number. Default: unset (false).

`config_file`¤

--config-file PATH: Configuration file(s).

`convention`¤

-c, --convention, --commit-style, --style CONVENTION: The commit convention to match against. Default: basic.

`debug_info`¤

--debug-info: Print debug information.

`filter_commits`¤

-F, --filter-commits RANGE: The Git revision-range filter to use (e.g. v1.2.0..). Default: no filter.

`help`¤

-h, --help: Show this help message and exit.

`in_place`¤

-i, --in-place: Insert new entries (versions missing from changelog) in-place. An output file must be specified. With custom templates, you can pass two additional arguments: --version-regex and --marker-line. When writing in-place, an in_place variable will be injected in the Jinja context, allowing to adapt the generated contents (for example to skip changelog headers or footers). Default: unset (false).

`input`¤

-I, --input FILE: Read from given file when creating release notes. Default: CHANGELOG.md.

`jinja_context`¤

-j, --jinja-context KEY=VALUE: Pass additional key/value pairs to the template. Option can be used multiple times. The key/value pairs are accessible as 'jinja_context' in the template.

`marker_line`¤

-m, --marker-line MARKER: A marker line at which to insert new entries (versions missing from changelog). If two marker lines are present in the changelog, the contents between those two lines will be overwritten (useful to update an 'Unreleased' entry for example). Default: .

`omit_empty_versions`¤

-E, --omit-empty-versions: Omit empty versions from the output. Default: unset (false).

`output`¤

-o, --output FILE: Output to given file. Default: standard output.

`parse_refs`¤

-r, --parse-refs: Parse provider-specific references in commit messages (GitHub/GitLab/Bitbucket issues, PRs, etc.). Default: unset (false).

`parse_trailers`¤

-T, --trailers, --git-trailers: Parse Git trailers in the commit message. See https://git-scm.com/docs/git-interpret-trailers. Default: unset (false).

`provider`¤

-p, --provider PROVIDER: Explicitly specify the repository provider. Default: unset.

`release_notes`¤

-R, --release-notes: Output release notes to stdout based on the last entry in the changelog. Default: unset (false).

`sections`¤

-s, --sections SECTIONS: A comma-separated list of sections to render. See the available sections for each supported convention in the description. Default: unset (None).

`template`¤

-t, --template TEMPLATE: The Jinja2 template to use. Prefix it with path: to specify the path to a Jinja templated file. Default: keepachangelog.

`version`¤

-V, --version: Show the current version of the program and exit.

`version_regex`¤

-g, --version-regex REGEX: A regular expression to match versions in the existing changelog (used to find the latest release) when writing in-place. The regular expression must be a Python regex with a version named group. Default: ^## \[(?P<version>v?[^\]]+).

`versioning`¤

-n, --versioning SCHEME: Versioning scheme to use when bumping and comparing versions. The selected scheme will impact the values accepted by the --bump option. Supported: pep440, semver. PEP 440 provides the following bump strategies: auto, epoch, release, major, minor, micro, patch, pre, alpha, beta, candidate, post, dev. Values auto, major, minor, micro can be suffixed with one of +alpha, +beta, +candidate, and/or +dev. Values alpha, beta and candidate can be suffixed with +dev. Examples: auto+alpha, major+beta+dev, micro+dev, candidate+dev, etc.. SemVer provides the following bump strategies: auto, major, minor, patch, release. See the docs for more information. Default: unset (semver).

`zerover`¤

-Z, --no-zerover: By default, breaking changes on a 0.x don't bump the major version, maintaining it at 0. With this option, a breaking change will bump a 0.x version to 1.0. Default: True.