Skip to main content

Getting Started

git-cliff can generate changelog files from the Git history by utilizing conventional commits as well as regex-powered custom parsers.

The changelog template can be customized with a configuration file to match the desired format.

Quickstart​

  1. Install git-cliff:
cargo install git-cliff

Also, see the other installation options.

  1. Initialize git-cliff:
git-cliff --init

Edit the default configuration (cliff.toml) as you like. Check out the examples for different templates.

  1. Generate a changelog:
git-cliff -o CHANGELOG.md

See the command-line usage examples.

note

The git cliff command can also be used interchangeably with git-cliff (with a -) in most environments (when git is installed). However, when using the NPM installation method, the git-cliff command should be used.

Contribute​

Contributions are highly appreciated! See the contribution guidelines for getting started.

Feel free to submit issues and toss ideas!

FAQ​

How should I write my commits?​

We recommend using a Git history that follows the Conventional Commits specification as the primary strategy. For example:

fix(parser): handle empty commit messages gracefully
feat(cli): add support for --dry-run flag
refactor(core)!: change internal API to use async/await

git-cliff’s default configuration is built around this convention, making it easy to generate clear, structured, and consistent changelogs by grouping commits (e.g., feat, fix, docs). The most important prefixes you should have in mind are:

  • fix: which represents bug fixes, and correlates to a SemVer patch.
  • feat: which represents a new feature, and correlates to a SemVer minor.
  • feat!:, or fix!:, refactor!:, etc., which represent a breaking change (indicated by the !) and will result in a SemVer major.

In addition to commit messages, git-cliff also supports parsing remote metadata from supported Git hosting services — such as pull request titles, numbers, and authors — using customizable regular expressions.

For example, GitHub pull request labels can be used as grouping keys, allowing changelogs to be organized based on custom PR label categories such as breaking-change, type/enhancement, or area/documentation.

How should I manage PRs?​

When working with a PR-based development flow, it’s important to adopt a merge strategy that preserves a clean and readable Git history—especially when changelogs are generated from commit metadata.

We recommend using squash merges for integrating PRs into the main branch. This approach has several benefits:

  • Linear history: PRs are merged as single commits, making the history easier to read and traverse.
  • Easier bug tracking: Tools like git bisect become more effective with a linear history.
  • Better compatibility with git-cliff: Since git-cliff generates changelogs from commit messages, using squash merges helps ensure that each PR corresponds to a single, coherent commit. Other merge strategies, such as rebase merges or merge commits, may fail to consistently associate PR-level context (e.g., title, labels, issue references) with a single commit.