Before you replace a manually written changelog with git-cliff, check which commits it leaves out. The documented default excludes messages that don't follow Conventional Commits. That can produce a tidy release note while leaving a change your users need to know about unmentioned. The configuration deserves as much attention as the template.
Unconventional commits need an explicit inclusion policy
git-cliff generates changelogs from Git history using Conventional Commits or custom regular-expression parsers. You can customize the output with a configuration file. This fits a maintainer who already has useful commit messages and wants control over grouping and presentation. It also gives a team with older, inconsistent history a way to write its own parsing rules.
The Git configuration reference explains the important default: filter_unconventional = true excludes unconventional commits. It documents a mixed-history configuration that keeps conventional parsing and puts other messages into an Other group. That's the sensible starting point for an evaluation if your repository hasn't always followed the same convention. Inspect that group before deciding to suppress it.
You can choose stricter behavior instead. With require_conventional = true, an unconventional commit can make generation fail. The documentation says this check happens after commit parsers, so explicitly skipped commits can avoid it. Don't mistake that setting for proof that every commit in the repository follows your policy. Decide which skips you intend to allow.
These controls make git-cliff attractive when you want to retain editorial ownership of release notes. They also make it a poor choice for someone who expects useful prose from messages such as "updates" without maintaining classification rules. A parser can classify the text it receives. You'll still need to explain the user consequence of a vaguely described change.
What happened when we ran it
Our November 6, 2026 sandbox run at commit 4f65432 installed dependencies in 29 seconds and built git-cliff in 187 seconds. The record lists 384 dependencies. Tests exited 101 after 173 seconds, with 153 passes and 5 failures out of 158 recorded tests.
The tail shows 126 passing and 5 failing tests in one result, plus a separate result with 27 passes. It names repository tests including repo::test::git_tags, repo::test::includes_root_commit and repo::test::resolves_existing_tag_with_name_and_message. The error directs a rerun of git-cliff-core --lib. Those names locate the failing area, but the supplied tail contains no assertion details or underlying error. We can't attribute the failures to Git identity, signing settings or a runtime version.
The sandbox configuration specified 3 CPUs, 12 GB RAM and image label lab-rust:1. That label establishes neither the actual Rust toolchain nor the operating system. The checkout held 539 files, approximately 18,621 source lines and 17.1 MB. The scan found 8 CI workflow files and a Dockerfile, with no tests directory detected. The named repository tests show why that last observation mustn't be read as an absence of tests.
This run establishes successful install and build steps alongside a failing test command. It provides no changelog-accuracy check against a real release, performance comparison or publishing exercise. Setup ease remains unassessed because a supported end-user installation and representative output were not verified.
Tag filters can change which release receives a commit
The configuration reference distinguishes skip_tags from ignore_tags: skipping drops commits from the changelog, while ignoring carries those commits into the next tag. A maintainer excluding prereleases needs to choose between those outcomes deliberately. Similar-looking filters can produce different release histories.
There is another documented boundary: when a commit has multiple tags, matching an ignored tag can cause all tags on that commit to be ignored. Teams tagging the same commit for several packages should check their actual tag layout before adopting a shared configuration. The path filters also deserve review: exclude_paths takes priority over include_paths. These are concrete reasons to avoid copying somebody else's configuration unchanged.
GitHub records the last push on November 2, 2026. Its recent issue and PR listing includes a changelog-generation performance report updated November 6, alongside recent pull-request activity. That shows ongoing use and maintenance discussion. It doesn't establish a performance defect in every repository or explain our failed tests. Our run measured no tag-scaling workload.
Choose another tool when releases need a different source of truth
semantic-release automates version selection, release-note generation and package publishing. Evaluate it when commit conventions should drive the whole release workflow. That scope is a reason to choose it, rather than a claim that it generates better prose or runs faster than git-cliff.
Changesets lets contributors declare how changes should be released, with a focus on monorepos and related packages. Evaluate it when a contributor's explicit release description should guide versioning and changelogs. Its repository warns that the development branch targets v3 and points v2 users to a maintenance branch. Choose the intended line before evaluating its workflow.
Documentation earns 4/5 on this editorial scale: 1 means essential instructions are missing, 2 means isolated examples leave the route unclear, 3 means an actionable route with gaps, 4 means detailed rules and explicit limits, and 5 requires independently verified instructions. The filter and tag documentation supports 4. Support quality and operational maturity remain unassessed.
Take a release you already understand and compare its human-written notes with git-cliff's output. Account for every missing change before adding the generator to CI. That comparison will tell you whether your commit policy can support the changelog you want to publish.