# git-cliff turns conventional commits into a changelog you control

> A Rust changelog generator that parses commit history, groups it with regular expressions, and renders it through a Tera template you write. The template is the point.

**orhun/git-cliff** — A highly customizable Changelog Generator that follows Conventional Commit specifications ⛰️ 

- Repository: https://github.com/orhun/git-cliff
- Website: https://git-cliff.org
- Stars: 12,329 · Forks: 336
- Language: Rust
- License: Apache-2.0
- Published: 2026-10-07 · Updated: 2026-10-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/orhun-git-cliff

## Three stages: parse, group, render

git-cliff does one thing, but it splits that thing into three replaceable stages, and understanding the split is what makes the project configurable rather than merely tweakable.

The first stage reads git history. The second decides what each commit is: type, scope, breaking or not, message, and which parts are breaking. The third renders. Every stage is controlled by `cliff.toml`, and the template in that file is a Tera template rather than a string format, which is why a changelog can have arbitrary structure and still be generated from data.

The project's description calls it a customizable changelog generator that follows Conventional Commit specifications, and the README adds a second path in: regex-powered custom parsers. So the conventional commit spec is the default vocabulary, not a requirement. If your team writes commit messages in some other shape, you write a regex parser for that shape and the rest of the pipeline stays the same.

The topic list confirms the intent, and it is a longer list than most: conventional-commit, semver, keepachangelog, changelog-generator and, notably, monorepo tooling sits alongside the obvious ones.

## Thirteen example configs are the real documentation

The `examples/` directory is the most useful thing in the repository, and it is the part a newcomer should open first. It holds thirteen ready-to-copy configurations.

They are named after what they produce rather than how they work: `minimal.toml`, `detailed.toml`, `unconventional.toml`, `scoped.toml`, `scopesorted.toml`, `statistics.toml`, `cocogitto.toml`. Then there are four that target a specific hosting format: `github.toml`, `github-keepachangelog.toml`, `gitlab.toml`, `gitlab-keepachangelog.toml`, and `azure-devops-keepachangelog.toml`.

The distinction in those names is the interesting part. Keep a Changelog is a different document format from a GitHub release note, and git-cliff ships separate templates for each rather than trying to be clever. `statistics.toml` is the outlier in spirit: it appears to add counts and summary statistics to the output, which is the sort of thing that reads well in a release announcement and terribly in a reference document.

If you are configuring this for the first time, `minimal.toml` is where you find the smallest thing that works, and `github.toml` is where you find the shape most projects actually want.

## Distribution: crates, Docker, npm and PyPI

The badges at the top of the README give the honest list. There is a crates.io release badge, a GitHub releases badge, a Docker Hub workflow for `orhunp/git-cliff`, and a docs badge pointing at `git-cliff-core` on docs.rs. The installation documentation is linked but not reproduced.

The repository tree shows how much of the delivery surface is kept in-tree: `npm/` and `pypi/` are directories, which is unusual for a Rust tool and means the npm and PyPI distributions are maintained here rather than by a separate wrapper project. There is also `flake.nix` and `flake.lock` for Nix, a `Dockerfile`, and a `rust-toolchain.toml` pinning the compiler.

The Dockerfile is where the feature flags become visible. The build compiles with three named features turned on:

```dockerfile
RUN cargo build --release --locked --no-default-features --features github --features gitlab --features bitbucket
COPY --from=builder /app/target/release/git-cliff /usr/local/bin
```

So the hosted-service integrations are optional compile-time features, and the container image ships the github, gitlab and bitbucket set. The `Cargo.toml` says the same thing about the shape of the code: two workspace members, `git-cliff-core` and `git-cliff`, so the parsing engine is usable as a library by something that is not the command line tool.

## What the container has to work around

The Dockerfile is worth reading past the build line, because the comments explain two Git quirks that would otherwise look strange.

The first is that git refuses to operate on a repository it considers unsafe, and a container working directory owned by a different user triggers exactly that. The workaround is written into the image's gitconfig:

```dockerfile
RUN echo '[safe]\n\tdirectory = *' > /etc/gitconfig
```

That is a blanket exemption, and the comment above it is explicit that everything in the container is mounted by the end user so some of git's protections have to be stepped around. It is fine for a CI job that mounts its own checkout and questionable as a pattern to copy elsewhere.

The second quirk is about identity rather than safety. Some CI environments, GitHub Actions among them, insist on running the entrypoint as root even when the mounted files belong to a normal user. So the image ships an entrypoint script that compares the effective user ID against the owner of the working directory and drops to match it. Also in that file: `ca-certificates` is installed explicitly, with a comment naming it as the requirement for the `--use-native-tls` argument.

None of this is glamorous and all of it is the cost of running a tool that shells out to git inside a container.

## Monorepos and the community around it

The README's documentation section links two community blog posts, and one of them names a specific problem: git-cliff and monorepos. That tells you the project has an opinion about multi-package repositories, and the topic list carries a `monorepo` tag to match. Monorepo support is not something most changelog generators attempt because the tag filtering and grouping logic differs per package, and a repository with a `packages/` layout needs more than a single regex pass.

The rest of the ecosystem integrations are listed too. An Emacs package, `git-cliff.el`, generates, updates and releases changelogs from inside the editor. The README also lists conference and podcast appearances, which is a reasonable proxy for how visible the project has become rather than a technical fact.

For comparison, the README names the alternatives honestly and in some cases accurately. git-journal is described as a git commit message and changelog generation framework, clog-cli as a generator of beautiful changelogs from commit history, cocogitto as a set of CLI tools for the conventional commit and semver specifications, and release-plz as a way to release Rust packages from CI. cliff-jumper is the interesting one: a Node CLI that combines git-cliff with conventional-recommended-bump, which tells you git-cliff does not do version bumping on its own.

## Where the README stops and the site takes over

This README is unusually short for a project of its age and it is honest about it. Four documentation links: installation, usage examples, configuration, templating. After that there is a blog list, media list, editor support, related projects, contributors, socials and the licence. There is no feature tour, no flag reference and not a single example of generated output.

That is a deliberate division. The site at git-cliff.org holds the documentation, and the templating category there is the part that matters, because the template is where the behaviour lives. The `cliff.toml` in the repository root is the project's own configuration, and `config/` is the schema and defaults that ship with the binary.

The maintenance picture is clear. Licence is Apache-2.0 or MIT at your choice, the copyright line runs 2021 to 2025, and the last push was on 2026-09-18 with v2.14.2 published the same day. `RELEASE.md` sits in the tree, which is a small signal worth noticing: the project documents how its own releases are made, and a tool that automates changelogs has no excuse for automating its own process sloppily.

## Conclusion

git-cliff is the right tool when your changelog format is a house style rather than a default, because the template is yours to write and the examples directory gives you thirteen starting points. It is the wrong tool when you want a changelog with no configuration, or when your commit messages were never conventional and no parser will fix that retroactively. Two checks decide it. First, look at `examples/minimal.toml` and `examples/github.toml` and see whether your target format is closer to what exists than to what you would write. Second, read the templating documentation, because the entire value of the project lives there and the README describes it in one sentence. Then run it against a real tag range before wiring it into CI, and read `RELEASE.md` to see how the maintainers treat the release process they are documenting.

## FAQ

### How do I install git-cliff?

The README links an installation page rather than listing commands, but its badges and tree show the channels: crates.io, GitHub releases, the `orhunp/git-cliff` Docker Hub image, Nix via the `flake.nix` in the repository, and maintained `npm/` and `pypi/` directories. The installation page at git-cliff.org covers the details.

### Does git-cliff bump the version number for me?

Not on its own. The README's related projects list includes cliff-jumper, a Node CLI that combines git-cliff with conventional-recommended-bump, and release-plz for releasing Rust packages from CI, which implies the version decision lives elsewhere. git-cliff's own job is generating the changelog from commit history.

### Can git-cliff handle commit messages that are not conventional commits?

Yes. The README describes git-cliff as using conventional commits as well as regex-powered custom parsers, and the examples directory includes an `unconventional.toml` alongside the rest. The configuration documentation holds the details on writing a parser.

## Sources

- [License: Apache-2.0](https://github.com/orhun/git-cliff/blob/main/LICENSE)
- [orhun/git-cliff on GitHub](https://github.com/orhun/git-cliff)
- [Project website](https://git-cliff.org)
- [README](https://github.com/orhun/git-cliff/blob/main/README.md)
- [Releases](https://github.com/orhun/git-cliff/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/orhun-git-cliff