Skip to main content
git-cliff uses a TOML or YAML configuration file to customize changelog generation. The configuration file defines how commits are parsed, grouped, and formatted into a changelog.

​
Configuration File Location

The configuration file is read from $HOME/git-cliff/cliff.toml if it exists. This location depends on your platform:
  • Linux: /home/<user>/.config/git-cliff/cliff.toml
  • Windows: C:\Users\<user>\AppData\Roaming\git-cliff\cliff.toml
  • macOS: /Users/<user>/Library/Application Support/git-cliff/cliff.toml

​
Initializing Configuration

To create a default configuration file in your project: 
git cliff --init
This creates a cliff.toml file in your current directory with default settings.

​
Configuration Structure

The configuration file is organized into four main sections:

Changelog

Configure header, body, footer templates and output settings

Git

Define commit parsing rules, filters, and git-specific options

Remote

Set up integration with GitHub, GitLab, Gitea, Bitbucket, and Azure DevOps

Bump

Configure semantic version bumping rules

​
Basic Example

Here’s a minimal configuration file: 
[changelog]
body = """
{% if version %}\n    ## {{ version | trim_start_matches(pat="v") }} - {{ timestamp | date(format="%Y-%m-%d") }}\n{% else %}\n    ## Unreleased\n{% endif %}\n{% for group, commits in commits | group_by(attribute="group") %}
    ### {{ group | upper_first }}
    {% for commit in commits %}\n        - {% if commit.breaking %}[**breaking**] {% endif %}{{ commit.message | upper_first }}
    {% endfor %}\n{% endfor %}\n
"""
This configuration uses Tera templating to generate a simple changelog with version headers and grouped commits.

​
Environment Variable Overrides

You can override any configuration option using environment variables with the format: 
GIT_CLIFF__<SECTION>__<FIELD_NAME>

​
Examples

​
GIT_CLIFF__CHANGELOG__FOOTER
string
Override the changelog footer:
export GIT_CLIFF__CHANGELOG__FOOTER="<!-- footer from env -->"
​
GIT_CLIFF__GIT__IGNORE_TAGS
string
Override the ignore_tags pattern:
export GIT_CLIFF__GIT__IGNORE_TAGS="v[0-9]+.[0-9]+.[0-9]+-rc[0-9]+"

​
Manifest Configuration

You can embed git-cliff configuration in your project manifest files: Cargo.toml (Rust projects): 
[package.metadata.git-cliff.changelog]
header = "Changelog"
trim = true

[package.metadata.git-cliff.git]
conventional_commits = true
pyproject.toml (Python projects): 
[tool.git-cliff.changelog]
header = "Changelog"
trim = true

[tool.git-cliff.git]
conventional_commits = true

​
Configuration Formats

git-cliff supports both TOML (recommended) and YAML formats: TOML (cliff.toml): 
[git]
conventional_commits = true
filter_unconventional = true
YAML (cliff.yaml): 
git:
  conventional_commits: true
  filter_unconventional: true

​
Default Configuration

See the default cliff.toml for a complete example with all available options.

​
Next Steps

Explore each configuration section in detail:

Build docs developers (and LLMs) love

Get started for freeTalk to us