git-cliff vs ShipChangelog: From Commit Log to Real Changelog
git-cliff is a good free tool, and it should exist: a Rust CLI that turns git history into a CHANGELOG.md, scriptable, configurable, and happy to run in any CI. Where the two tools actually differ is not generation — it is everything after the text is produced: who reads it, where it lives, and what it says to each of them.
What git-cliff does
In most setups, git-cliff reads your git history (typically configured around conventional commits), groups the changes, and renders a CHANGELOG.md file with a template you control. It is free, open source, and the template system is genuinely flexible. For a library whose readers are other developers, that is a complete workflow: commit with conventional messages, run git cliff before a tag, ship the file in the repo.
Its limits are structural, not bugs:
- The output is a file. It lives where
CHANGELOG.mdlives — in the repo. Unless you build the publishing step yourself, your users never see it. - One reader. There is no notion of audience. The changelog is written at one level of abstraction, for the person who reads commits.
- It depends on discipline. Conventional-commit parsing is only as good as your commit messages; messy history produces a messy file.
- No distribution. No hosted page, no RSS, no email digest, no badge.
What ShipChangelog does
ShipChangelog targets the other end of the spectrum: not a file in the repo, but a hosted changelog your users actually visit. You connect a GitHub repo (or a CI webhook); merged PRs become draft entries you can edit; major-version bumps and BREAKING CHANGE markers are detected and highlighted; and each release is generated in three audience versions — developer, customer, stakeholder. The page, RSS feed, and email digest are included, and the Pro plan adds a custom domain and private changelogs.
Side by side
| Dimension | git-cliff | ShipChangelog |
|---|---|---|
| Cost | Free, open source | Free tier (1 repo, 5 entries/mo); Pro $12.99/mo |
| Runs | Your CI, your machine | SaaS; repo or CI webhook |
| Output | CHANGELOG.md in your repo | Hosted page + RSS + email digest |
| Source | Git history, typically conventional commits | Merged PRs (titles, labels, markers) |
| Audiences | One | Three (dev / customer / stakeholder) |
| Breaking changes | Template sections only | Detected and highlighted |
| Discipline required | High (commit messages) | Low (PR titles and labels) |
| Customization | Full template control | Edit generated entries before publishing |
When to pick which
Pick git-cliff when you maintain a library or CLI, your readers are developers who already have the repo, you want zero vendor and full control, and your commit messages are conventional (or you are willing to make them so). If that is your situation, stop reading: git-cliff is the right tool, and ShipChangelog is not solving your problem.
Pick ShipChangelog when you ship a product with non-developer users; the changelog needs to be a public page, not a file; you want three audience versions of one release; your commit history is messier than your PR titles; or you simply do not want to own the publishing pipeline. This is the classic OSS-to-hosted upgrade path: git-cliff for the in-repo record, a hosted service for the page users read.
The two are not mutually exclusive. Many teams keep git-cliff generating the in-repo CHANGELOG.md for contributors while a hosted service carries the public, multi-audience page. If your current pain is that auto-generated notes "lack business-aware context," that is the audience problem this article is about, and the release notes for multiple audiences guide covers the workflow in depth.
ShipChangelog
ShipChangelog is the hosted half of this comparison: connect a repo or CI webhook, review the draft entries it writes from your merged PRs, and publish one release to three audiences. Free for one repo with 5 entries a month; Pro at $12.99/month adds three repos, unlimited entries, breaking-change detection, a custom domain, and private changelogs.
FAQ
Can I use git-cliff and ShipChangelog together?
Yes. Use git-cliff in CI for the in-repo CHANGELOG.md that contributors read, and ShipChangelog for the hosted, multi-audience page. They read different sources (commits versus merged PRs), so they rarely even conflict.
My commit messages are not conventional. Does that kill git-cliff?
It makes its output noisy. You can fix the messages or loosen the config, but the underlying constraint is real: git-cliff's quality tracks your commit discipline, while PR-based tools only need PR titles and labels to be decent.
Will SaaS tools eventually replace git-cliff?
Unlikely for its niche. A free, scriptable, in-repo changelog generator has a durable audience of library maintainers. The tools are complementary: file versus page, one reader versus three.
ShipChangelog writes these changelogs for you — start free with 1 repo.