Examples
The default configuration file (cliff.toml
) can be generated using the --init
flag:
# create cliff.toml
git cliff --init
Then 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:
# it doesn't have to be an existing tag
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 changelog for a specific commit range
git cliff 4c7b043..a440c6e
git cliff 4c7b043..HEAD
git cliff HEAD~2..
Generate a changelog scoped to a specific directory (useful for monorepos):
git cliff --include-path "**/*.toml" --include-path "*.md"
git cliff --exclude-path ".github/*"
Generate a changelog for multiple git repositories:
# merges the commit history
git cliff --repository path1 path2
Generate a changelog that includes yet unexisting commit messages:
commit_msg="chore(release): update CHANGELOG.md for 1.0.0"
# You might need to include the commit messages that do not exist
# for testing purposes or solving the chicken-egg problem.
git cliff --with-commit "$commit_msg" -o CHANGELOG.md
git add CHANGELOG.md && git commit -m "$commit_msg"
The commit SHA will be empty as default when
--with-commit
is used. Specify the hash with a message separated by single whitespace for setting the commit SHA. e.g.--with-commit "8f55e69eba6e6ce811ace32bd84cc82215673cb6 feat: add X"
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:
git cliff --output CHANGELOG.md
Print the changelog context as JSON:
# print context to stdout
git cliff --context
# save context to a file
git cliff --context --output context.json
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
git cliff --unreleased --tag 1.0.0 --prepend CHANGELOG.md
Set/remove the changelog parts:
git cliff --body $template --strip footer
Also, see the release script of this project which sets the changelog as a message of an annotated tag.