Git Cliff
2 min read
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:
sh
git-cliff --init
Edit the default configuration (cliff.toml) as you like. Check out the examples for different templates.
Generate a changelog:
sh
git-cliff -o CHANGELOG.md
Examples
To simply create a changelog at your projects git root directory:
sh
# same as running `git-cliff --config cliff.toml --repository .`
# same as running `git-cliff --workdir .`
git cliff
Set a tag for the unreleased changes:
sh
# 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:
sh
# 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):
sh
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:
sh
git cliff --use-branch-tags
Sort the commits inside sections:
sh
# 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:
sh
# Process in topological order instead of chronological.
git cliff --topo-order
Save the changelog file to the specified file:
sh
# 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:
sh
# 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:
sh
git cliff --body $template --strip footer
Skip running the commands defined in pre/postprocessors.
sh
# No external command execution
git cliff --no-exec