Initializing

The default configuration file (cliff.toml) can be generated using the --init flag:

# create cliff.toml
git cliff --init

# create a config file with a custom name
git-cliff --init --config custom.toml

There are also other templates under the examples directory. See the template examples for previewing the templates.

To initialize git-cliff with one of those templates, simply use the name of the template:

# create cliff.toml with Keep a Changelog format
git cliff --init keepachangelog

Also, you can use a template without creating the configuration file. Just give the name of the template to the --config option as follows:

# generate a changelog with using the built-in "detailed" template
git cliff --config detailed

Here are the list of available templates:

• keepachangelog.toml: changelog in Keep a Changelog format.
• github.toml: changelog in the GitHub's format.
• github-keepachangelog.toml: combination of the previous two formats.
• gitlab.toml: release notes format tailored for GitLab Releases.
• gitlab-keepachangelog.toml: combination of GitLab and Keep a Changelog format.
• detailed.toml: changelog that contains links to the commits.
• minimal.toml: minimal changelog.
• scoped.toml: changelog with commits are grouped by their scopes.
• scopesorted.toml: changelog with commits grouped by their scopes and sorted by group.
• cocogitto.toml: changelog similar to cocogitto's format.
• unconventional.toml: changelog for unconventional commits.

tip

It is also possible to use a remote URL for the configuration file as follows:

git cliff --config-url https://github.com/orhun/git-cliff/blob/main/examples/github-keepachangelog.toml?raw=true

User-defined templates

In addition to the built-in templates, you can keep your own templates in a directory and use them with --init by pointing git-cliff at that directory with --templates-dir (or the GIT_CLIFF_TEMPLATES_DIR environment variable):

# initialize using ~/my-templates/company.toml
git cliff --templates-dir ~/my-templates --init company

A user-defined template takes precedence over a built-in template of the same name, so you can override the shipped templates by placing a .toml file with the same name in your templates directory.

To list every available template — built-in and user-defined — use --list-templates (useful for shell/editor completion):

# print built-in template names
git cliff --list-templates

# also include user-defined templates from a directory
git cliff --list-templates --templates-dir ~/my-templates