Git Cliff

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.

Usage

Initialize git-cliff:

git-cliff --init

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

Generate a changelog:

git-cliff -o CHANGELOG.md

Examples

To simply create a changelog at your projects git root directory:

# same as running `git-cliff --config cliff.toml --repository .`
# same as running `git-cliff --workdir .`
git cliff

Set a tag for the unreleased changes:

# generates a changelog for the tag '1.0.0' without creating the tag itself
git cliff --tag 1.0.0

Generate a changelog for a certain part of git history:

# only takes the latest tag into account
git cliff --latest
# only takes the current tag into account
# useful if you checkout a specific tag (e.g. `git checkout v0.0.1`)
# (requires a tag to be present for the current commit (i.e. HEAD))
git cliff --current
 
# generate changelog for unreleased commits
git cliff --unreleased
git cliff --unreleased --tag 1.0.0

Generate a changelog for a specific commit range (based on git ranges):

git cliff 4c7b043..a440c6e
git cliff 4c7b043..HEAD
git cliff HEAD~2..
git cliff v2.2.1..
git cliff v0.1.0..HEAD

Only include the tags from the current branch:

git cliff --use-branch-tags

Sort the commits inside sections:

# The oldest commit will be on top.
# (default)
git cliff --sort oldest
 
# The newest commit will be on top.
git cliff --sort newest

Sort the tags in topological order:

# Process in topological order instead of chronological.
git cliff --topo-order

Save the changelog file to the specified file:

# Set output path
git cliff --output CHANGELOG.md
 
# Without path, the default is `CHANGELOG.md`
git cliff -o

Prepend new changes to an existing changelog file:

# 1- changelog header is removed from CHANGELOG.md
# 2- new entries are prepended to CHANGELOG.md without footer part
# the --prepend option is incompatible with -o (output) if the file paths are equal
git cliff --unreleased --tag 1.0.0 --prepend CHANGELOG.md

Set/remove the changelog parts:

git cliff --body $template --strip footer

Skip running the commands defined in pre/postprocessors.

# No external command execution
git cliff --no-exec