Skip to main content

Configuration

git-cliff configuration file supports TOML (preferred) and YAML formats.

File Path​

git-cliff will look for a configuration file first in the project directory, then in the global user directory. If no configuration file is found, git-cliff will use the default configuration values. See cliff.toml for the default configuration values.

It looks for the following configuration files in this order:

  • cliff.toml
  • .cliff.toml
  • .config/cliff.toml
  • $HOME/cliff.toml
  • $HOME/.cliff.toml
  • $HOME/.config/cliff.toml

If no configuration file is found in the current directory, it will search the parent directories.

Home Directory​

The $HOME directory is dependent on the platform. For example:

  • on Linux: /home/<user>
  • on Windows: C:\Users\<user>\AppData\Roaming
  • on macOS: /Users/<user>/Library/Application Support

Environment Configuration Overrides​

It's possible to use environment variables to override configuration elements. If an environment variable matches a configuration element, the variable's value will be used instead of the element's.

Format:

[PREFIX]__[CONFIG SECTION]__[FIELD NAME]

Examples​

To override the footer element:

export GIT_CLIFF__CHANGELOG__FOOTER="<!-- footer from env -->"

To override the ignore_tags element:

export GIT_CLIFF__GIT__IGNORE_TAGS="v[0-9]+.[0-9]+.[0-9]+-rc[0-9]+"