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¤

(docs)

  • -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¤

(docs)

  • -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).

bumped_version¤

  • --bumped-version: Show bumped version and exit.

config_file¤

(docs)

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

convention¤

(docs)

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

debug_info¤

  • --debug-info: Print debug information.

filter_commits¤

(docs)

  • -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¤

(docs)

  • -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 Parameters: --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).

include_all¤

(docs)

  • -a, --include-all: Include all commits, even those without a recognized type. These commits will be rendered in a 'Misc' section at the end of each version. Default: unset (false).

input¤

(docs)

  • -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¤

(docs)

  • -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: <!-- insertion marker -->.

omit_empty_versions¤

(docs)

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

output¤

(docs)

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

parse_refs¤

(docs)

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

parse_trailers¤

(docs)

provider¤

(docs)

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

release_notes¤

(docs)

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

sections¤

(docs)

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

template¤

(docs)

  • -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¤

(docs)

  • -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¤

(docs)

  • -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¤

(docs)

  • -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.