Git Cliff

git-cliff

git-cliff generates beautiful, customizable changelogs from git history using conventional commits and regex-powered custom parsers. The changelog body is a Tera template (similar to Jinja2/Django templates).

Core Concepts

• Config file: cliff.toml in the project root (or ~/.config/git-cliff/cliff.toml globally)
• Template engine: Tera — {{ variable }}, {% for %}, {% if %}, filters like | upper_first
• Conventional commits: <type>[scope]: <description> — types include feat, fix, docs, refactor, perf, test, chore, style, build, ci
• Breaking changes: feat!: / fix!: suffix or BREAKING CHANGE: footer → SemVer major bump
• feat: → minor bump · fix: → patch bump

Quickstart

git-cliff --init          # scaffold cliff.toml in the current directory
git-cliff -o CHANGELOG.md # generate full changelog from all history

CLI Reference

Boolean flags

Options

Remote Integration

git-cliff --github-token $GITHUB_TOKEN --github-repo owner/repo
git-cliff --gitlab-token $GITLAB_TOKEN --gitlab-repo owner/repo
# Also: --gitea-*, --bitbucket-*, --azure-devops-*

cliff.toml Schema

[changelog]
header = "# Changelog\n\nAll notable changes to this project will be documented in this file.\n"
body = """
{% if version %}
## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
{% else %}
## [unreleased]
{% endif %}
{% for group, commits in commits | group_by(attribute="group") %}
### {{ group | upper_first }}
{% for commit in commits %}
- {% if commit.scope %}*({{ commit.scope }})* {% endif %}\
  {% if commit.breaking %}[**breaking**] {% endif %}\
  {{ commit.message | upper_first }}
{% endfor %}
{% endfor %}
"""
footer = "<!-- generated by git-cliff -->"
trim = true          # strip leading/trailing whitespace from rendered body
# render_always = false   # render body even when there are no releases
# output = "CHANGELOG.md" # set default output path in config

postprocessors = [
  # Regex replace across the final output string:
  # { pattern = "\\(#([0-9]+)\\)", replace = "([#${1}](https://github.com/owner/repo/issues/${1}))" }
]

[git]
conventional_commits = true    # parse <type>[scope]: <desc> format
filter_unconventional = true   # exclude non-conventional commits
# require_conventional = false # fail if any included commit is non-conventional
# split_commits = false        # treat each commit body line as its own commit

commit_preprocessors = [
  # Mutate commit messages before parsing:
  # { pattern = " +", replace = " " }   # collapse multiple spaces
  # { pattern = "Merge pull request #([0-9]+) from [^ ]+", replace = "PR #${1}:" }
]

commit_parsers = [
  { message = "^feat",              group = "Features" },
  { message = "^fix",               group = "Bug Fixes" },
  { message = "^doc",               group = "Documentation" },
  { message = "^perf",              group = "Performance" },
  { message = "^refactor",          group = "Refactor" },
  { message = "^style",             group = "Styling" },
  { message = "^test",              group = "Testing" },
  { message = "^chore|^ci|^build",  group = "Miscellaneous Tasks" },
  { message = "^revert",            skip = true },
  # { body = ".*security",          group = "Security" },
  # { footer = "^changelog: ?ignore", skip = true },
  # { sha = "abc1234",              skip = true },
]

protect_breaking_commits = false  # never skip breaking changes, even if a parser would
filter_commits = false            # if true, drop commits not matched by any parser
# fail_on_unmatched_commit = false

tag_pattern = "v[0-9].*"    # regex for recognizing version tags
# skip_tags = "v0.1.0-beta.1"
# ignore_tags = "-rc[0-9]+$"  # roll RC commits into the next full release

topo_order = false           # topological tag ordering
sort_commits = "oldest"      # oldest | newest

link_parsers = [
  # Extract issue links from commit messages:
  # { pattern = "#(\\d+)", href = "https://github.com/owner/repo/issues/$1" },
]

# limit_commits = 100
# include_paths = ["src/", "lib/**"]
# exclude_paths = ["vendor/"]

Tera Template Context

The body template receives one release object per tag. header and footer receive the full releases array.

Release fields

Commit fields

Useful Tera patterns

{# Group by group label and list scoped commits #}
{% for group, commits in commits | group_by(attribute="group") %}
### {{ group | upper_first }}
{% for commit in commits | sort(attribute="message") %}
- {% if commit.scope %}*({{ commit.scope }})* {% endif %}{{ commit.message | upper_first }}
{% endfor %}
{% endfor %}

{# Highlight breaking changes separately #}
{% set breaking = commits | filter(attribute="breaking", value=true) %}
{% if breaking | length > 0 %}
### ⚠️ Breaking Changes
{% for commit in breaking %}
- {{ commit.breaking_description | default(value=commit.message) | upper_first }}
{% endfor %}
{% endif %}

{# Comparison links in footer using previous version #}
{% for release in releases %}
{% if release.previous.version %}
[{{ release.version }}]: https://github.com/owner/repo/compare/{{ release.previous.version }}..{{ release.version }}
{% endif %}
{% endfor %}

{# Trim version prefix for display #}
## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}

Key Tera built-ins: upper_first, lower, upper, trim, trim_start_matches(pat=...), replace(from=..., to=...), indent(prefix=...), group_by(attribute=...), filter(attribute=..., value=...), sort(attribute=...), unique, length, date(format=...), default(value=...), join(sep=...)

Common Workflows

1. Initialize and generate full changelog

git-cliff --init           # creates cliff.toml
git-cliff -o CHANGELOG.md  # writes complete changelog

2. Preview unreleased changes

git-cliff --unreleased
git-cliff --unreleased --tag 2.0.0  # label what the next release will be

3. Prepend unreleased to existing changelog (typical release flow)

git-cliff --unreleased --tag v1.3.0 --prepend CHANGELOG.md
# Note: --prepend and -o with the same path are incompatible

4. Auto-bump + prepend (fully automated release)

VERSION=$(git-cliff --bumped-version)
git-cliff --unreleased --tag "$VERSION" --prepend CHANGELOG.md
git add CHANGELOG.md && git commit -m "chore(release): $VERSION"
git tag "$VERSION" && git push --follow-tags

5. Generate for a specific range

git-cliff v1.0.0..HEAD
git-cliff v1.0.0..v2.0.0
git-cliff HEAD~10..        # last 10 commits only

6. Latest release notes only

git-cliff --latest -o RELEASE_NOTES.md
git-cliff --latest --strip all   # body only, no header/footer

7. Debug your template

git-cliff --context                    # print full JSON context
git-cliff --context | jq '.[0].commits[] | {group, scope, message}'

8. Monorepo per-package changelogs

git-cliff --include-path "packages/my-lib/**" \
          --tag-pattern "my-lib-v[0-9].*" \
          --tag my-lib-v1.0.0 \
          -o packages/my-lib/CHANGELOG.md

9. GitHub integration (PR titles, authors, labels)

GITHUB_TOKEN=xxx git-cliff --github-repo owner/repo -o CHANGELOG.md

10. CI/CD (GitHub Actions example)

- name: Generate changelog
  run: |
    VERSION=$(git-cliff --bumped-version)
    git-cliff --unreleased --tag "$VERSION" --prepend CHANGELOG.md
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Environment Variables

Config field overrides use the pattern GIT_CLIFF__<SECTION>__<FIELD> (double underscore):

export GIT_CLIFF__CHANGELOG__FOOTER="<!-- generated by git-cliff -->"
export GIT_CLIFF__GIT__IGNORE_TAGS="v[0-9]+\.[0-9]+\.[0-9]+-rc[0-9]+"
export GIT_CLIFF_CONFIG=./custom-cliff.toml
export GIT_CLIFF_OUTPUT=CHANGELOG.md
export GITHUB_TOKEN=ghp_xxx  # for GitHub remote integration

Tips & Patterns

• Debug first: Run git-cliff --context | jq to see exactly what data your template receives before writing the template.
• protect_breaking_commits = true: Ensures breaking changes always appear even if a skip rule would otherwise hide them.
• filter_commits = true: Drop any commit not matched by commit_parsers — great for noise-free changelogs.
• Opt-out per commit: Add { footer = "^changelog: ?ignore", skip = true } to let authors mark individual commits as "don't include".
• Monorepo: Use --include-path per package with per-package tag patterns. Version tags can be prefixed: my-pkg-v1.0.0.
• PR labels as groups: With GitHub remote integration, match remote.pr_labels in commit_parsers to group by PR label categories.
• split_commits = true: Treats each line of a commit body as a separate entry — useful when squash merges pack multiple changes into one commit message.
• ignore_tags vs skip_tags: ignore_tags rolls the commits into the next release; skip_tags drops them entirely.
• Postprocessors: Run regex replacements on the final rendered changelog string — useful for linkifying issue numbers globally.

Reference

• Full docs: https://git-cliff.org/docs/
• Configuration: https://git-cliff.org/docs/configuration
• Templating: https://git-cliff.org/docs/category/templating
• Template examples: https://git-cliff.org/docs/templating/examples
• CLI args: https://git-cliff.org/docs/usage/args