About
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.
Table of Contents
Installation
From crates.io
git-cliff can be installed from crates.io:
cargo install git-cliff
Using pacman
If you are using Arch Linux, git-cliff can be installed from the community repository:
pacman -S git-cliff
Binary Releases
See the available binaries for different operating systems/architectures from the releases page.
Usage
Command Line Arguments
git-cliff [FLAGS] [OPTIONS] [RANGE]
Flags:
-v, --verbose Increases the logging verbosity
-i, --init Writes the default configuration file to cliff.toml
-l, --latest Processes the commits starting from the latest tag
-u, --unreleased Processes the commits that do not belong to a tag
-h, --help Prints help information
-V, --version Prints version information
Options:
-c, --config Sets the configuration file [env: CONFIG=] [default: cliff.toml]
-w, --workdir Sets the working directory [env: WORKDIR=]
-r, --repository Sets the repository to parse commits from [env: REPOSITORY=]
-p, --prepend Prepends entries to the given changelog file [env: PREPEND=]
-o, --output Writes output to the given file [env: OUTPUT=]
-t, --tag Sets the tag for the latest version [env: TAG=]
-b, --body Sets the template for the changelog body [env: TEMPLATE=]
-s, --strip Strips the given parts from the changelog [possible values: header, footer, all]
Args:
Sets the commit range to process
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:
git cliff --tag 1.0.0
Create a changelog for a certain part of git history:
# only takes the latest tag into account
# (requires at least 2 tags)
git cliff --latest
# 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..
Save the changelog file to the specified file:
git cliff --output CHANGELOG.md
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.
Docker
The easiest way of running git-cliff (in the git root directory with configuration file present) is to use the available tags from Docker Hub:
docker run -t -v "$(pwd)/.git":/app/ orhunp/git-cliff:latest
Or you can use the image from the GitHub Package Registry:
docker run -t -v "$(pwd)/.git":/app/ docker.pkg.github.com/orhun/git-cliff/git-cliff:latest
Also, you can build the image yourself using docker build -t git-cliff . command.
GitHub Action
It is possible to generate changelogs using GitHub Actions via git-cliff-action.
- name: Generate a changelog
uses: orhun/git-cliff-action@v1
with:
config: cliff.toml
args: --verbose
env:
OUTPUT: CHANGELOG.md
See the repository for other examples.
Also, see the continuous deployment workflow of this project which sets the release notes for GitHub releases using this action.
Configuration File
git-cliff configuration file supports TOML (preferred) and YAML formats.
The configuration file is read from $HOME/git-cliff/cliff.toml if the file exists. This location depends on the platform, for example:
- on Linux:
/home//.config/git-cliff/cliff.toml - on Windows:
C:\Users\\AppData\Roaming\git-cliff\cliff.toml - on macOS:
/Users//Library/Application Support/git-cliff/cliff.toml
See config/cliff.toml for the default configuration values.
changelog
This section contains the configuration options for changelog generation.
[changelog]
header = "Changelog"
body = """
{% for group, commits in commits | group_by(attribute="group") %}
### {{ group | upper_first }}
{% for commit in commits %}
- {{ commit.message | upper_first }}
{% endfor %}
{% endfor %}
"""
trim = true
footer = ""
header
Header text that will be added to the beginning of the changelog.
body
Body template that represents a single release in the changelog.
See templating for more detail.
trim
If set to true, leading and trailing whitespaces are removed from the body.
It is useful for adding indentation to the template for readability, as shown in the example.
footer
Footer text that will be added to the end of the changelog.
git
This section contains the parsing and git related configuration options.
[git]
conventional_commits = true
commit_parsers = [
{ message = "^feat*", group = "Features"},
{ message = "^fix*", group = "Bug Fixes"},
{ message = "^doc*", group = "Documentation"},
{ message = "^perf*", group = "Performance"},
{ message = "^refactor*", group = "Refactor"},
{ message = "^style*", group = "Styling"},
{ message = "^test*", group = "Testing"},
]
filter_commits = false
tag_pattern = "v[0-9]*"
skip_tags = "v0.1.0-beta.1"
conventional_commits
If set to true, parses the commits according to the Conventional Commits specifications.
The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with SemVer, by describing the features, fixes, and breaking changes made in commit messages.
The commit message should be structured as follows:
[optional scope]:
[optional body]
[optional footer(s)]
e.g. feat(parser): add ability to parse arrays
commit_parsers
An array of commit parsers for determining the commit groups by using regex.
Examples:
{ message = "^feat*", group = "Features"}- Group the commit as "Features" if the commit message (description) starts with "feat".
{ body = ".*security", group = "Security"}- Group the commit as "Security" if the commit body contains "security".
{ message = ".*deprecated", body = ".*deprecated", group = "Deprecation"}- Group the commit as "Deprecation" if the commit body and message contains "deprecated".
{ message = "^revert*", skip = true}- Skip processing the commit if the commit message (description) starts with "revert".
filter_commits
If set to true, commits that are not matched by commit parsers are filtered out.
tag_pattern
A glob pattern for matching the git tags.
e.g. It processes the same tags as the output of the following git command:
git tag --list 'v[0-9]*'
skip_tags
A regex for skip processing the matched tags.
Templating
A template is a text where variables and expressions get replaced with values when it is rendered.
Context
Context is the model that holds the required data for a template rendering. The JSON format is used in the following examples for the representation of a context.
Conventional Commits
conventional_commits = true
For a conventional commit like this,
[scope]:
[body]
[footer(s)]
following context is generated to use for templating:
{
"version": "v0.1.0-rc.21",
"commits": [
{
"id": "e795460c9bb7275294d1fa53a9d73258fb51eb10",
"group": " (overrided by commit_parsers)" ,
"scope": "[scope]",
"message": "" ,
"body": "[body]",
"footers": ["[footer]", "[footer]"],
"breaking_description": "" ,
"breaking": false
}
],
"commit_id": "a440c6eb26404be4877b7e3ad592bfaa5d4eb210 (release commit)",
"timestamp": 1625169301,
"previous": {
"version": "previous release"
}
}
Breaking Changes
breaking flag is set to true when the commit has an exclamation mark after the commit type and scope, e.g.:
feat(scope)!: this is a breaking change
Or when the BREAKING CHANGE: footer is defined:
feat: add xyz
BREAKING CHANGE: this is a breaking change
breaking_description is set to the explanation of the breaking change. This description is expected to be present in the BREAKING CHANGE footer. However, if it's not provided, the message is expected to describe the breaking change.
Non-Conventional Commits
conventional_commits = false
If conventional_commits is set to false, then some of the fields are omitted from the context or squashed into the message field:
{
"version": "v0.1.0-rc.21",
"commits": [
{
"id": "e795460c9bb7275294d1fa53a9d73258fb51eb10",
"group": "(overrided by commit_parsers)",
"message": "(whole commit message including description, footers, etc.)"
}
],
"commit_id": "a440c6eb26404be4877b7e3ad592bfaa5d4eb210 (release commit)",
"timestamp": 1625169301,
"previous": {
"version": "previous release"
}
}
Syntax
git-cliff uses Tera as the template engine. It has a syntax based on Jinja2 and Django templates.
There are 3 kinds of delimiters and those cannot be changed:
{{and}}for expressions{%or{%-and%}or-%}for statements{#and#}for comments
See the Tera Documentation for more information about control structures, built-ins filters, etc.
Custom built-in filters that git-cliff uses:
upper_first: Converts the first character of a string to uppercase.
Examples
Examples are based on the following Git history:
* df6aef4 (HEAD -> master) feat(cache): use cache while fetching pages
* a9d4050 feat(config): support multiple file formats
* 06412ac (tag: v1.0.1) chore(release): add release script
* e4fd3cf refactor(parser): expose string functions
* ad27b43 (tag: v1.0.0) docs(example)!: add tested usage example
* 9add0d4 fix(args): rename help argument due to conflict
* a140cef feat(parser): add ability to parse arrays
* 81fbc63 docs(project): add README.md
* a78bc36 Initial commit
See examples directory for example configuration files.
If you have a custom configuration file that you are using for your project(s), consider sharing it with us by submitting a pull request!
Basic
Raw Output
# Changelog
All notable changes to this project will be documented in this file.
## [unreleased]
### Features
- Support multiple file formats
- Use cache while fetching pages
## [1.0.1] - 2021-07-18
### Miscellaneous Tasks
- Add release script
### Refactor
- Expose string functions
## [1.0.0] - 2021-07-18
### Bug Fixes
- Rename help argument due to conflict
### Documentation
- Add README.md
- Add tested usage example
### Features
- Add ability to parse arrays
Rendered Output
Changelog
All notable changes to this project will be documented in this file.
[unreleased]
Features
- Support multiple file formats
- Use cache while fetching pages
[1.0.1] - 2021-07-18
Miscellaneous Tasks
- Add release script
Refactor
- Expose string functions
[1.0.0] - 2021-07-18
Bug Fixes
- Rename help argument due to conflict
Documentation
- Add README.md
- Add tested usage example
Features
- Add ability to parse arrays
Detailed
Raw Output
# Changelog
All notable changes to this project will be documented in this file.
## [unreleased]
### Features
- Support multiple file formats ([a9d4050](a9d4050212a18f6b3bd76e2e41fbb9045d268b80))
- Use cache while fetching pages ([df6aef4](df6aef41292f3ffe5887754232e6ea7831c50ba5))
## [1.0.1] - 2021-07-18
[ad27b43](ad27b43e8032671afb4809a1a3ecf12f45c60e0e)...[06412ac](06412ac1dd4071006c465dde6597a21d4367a158)
### Miscellaneous Tasks
- Add release script ([06412ac](06412ac1dd4071006c465dde6597a21d4367a158))
### Refactor
- Expose string functions ([e4fd3cf](e4fd3cf8e2e6f49c0b57f66416e886c37cbb3715))
## [1.0.0] - 2021-07-18
### Bug Fixes
- Rename help argument due to conflict ([9add0d4](9add0d4616dc95a6ea8b01d5e4d233876b6e5e00))
### Documentation
- Add README.md ([81fbc63](81fbc6365484abf0b4f4b05d384175763ad8db44))
- Add tested usage example ([ad27b43](ad27b43e8032671afb4809a1a3ecf12f45c60e0e))
### Features
- Add ability to parse arrays ([a140cef](a140cef0405e0bcbfb5de44ff59e091527d91b38))
Rendered Output
Changelog
All notable changes to this project will be documented in this file.
[unreleased]
Features
[1.0.1] - 2021-07-18
Miscellaneous Tasks
- Add release script (06412ac)
Refactor
- Expose string functions (e4fd3cf)
[1.0.0] - 2021-07-18
Bug Fixes
- Rename help argument due to conflict (9add0d4)
Documentation
Features
- Add ability to parse arrays (a140cef)
Scoped
Raw Output
# Changelog
All notable changes to this project will be documented in this file.
## [unreleased]
### Features
#### Cache
- Use cache while fetching pages
#### Config
- Support multiple file formats
## [1.0.1] - 2021-07-18
### Miscellaneous Tasks
#### Release
- Add release script
### Refactor
#### Parser
- Expose string functions
## [1.0.0] - 2021-07-18
### Bug Fixes
#### Args
- Rename help argument due to conflict
### Documentation
#### Example
- Add tested usage example
#### Project
- Add README.md
### Features
#### Parser
- Add ability to parse arrays
Rendered Output
Changelog
All notable changes to this project will be documented in this file.
[unreleased]
Features
Cache
- Use cache while fetching pages
Config
- Support multiple file formats
[1.0.1] - 2021-07-18
Miscellaneous Tasks
Release
- Add release script
Refactor
Parser
- Expose string functions
[1.0.0] - 2021-07-18
Bug Fixes
Args
- Rename help argument due to conflict
Documentation
Example
- Add tested usage example
Project
- Add README.md
Features
Parser
- Add ability to parse arrays
Keep a Changelog
Raw Output
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [unreleased]
### Added
- Support multiple file formats
### Changed
- Use cache while fetching pages
## [1.0.1] - 2021-07-18
### Added
- Add release script
### Changed
- Expose string functions
## [1.0.0] - 2021-07-18
### Added
- Add README.md
- Add ability to parse arrays
- Add tested usage example
### Fixed
- Rename help argument due to conflict
Rendered Output
Changelog
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
[unreleased]
Added
- Support multiple file formats
Changed
- Use cache while fetching pages
[1.0.1] - 2021-07-18
Added
- Add release script
Changed
- Expose string functions
[1.0.0] - 2021-07-18
Added
- Add README.md
- Add ability to parse arrays
- Add tested usage example
Fixed
- Rename help argument due to conflict
Similar Projects
- git-journal - The Git Commit Message and Changelog Generation Framework
- clog-cli - Generate beautiful changelogs from your Git commit history
- relnotes - A tool to automatically generate release notes for your project.
- cocogitto - A set of CLI tools for the conventional commit and semver specifications.
License
GNU General Public License (v3.0)
Copyright
Copyright © 2021, git-cliff contributors
23 Oct 12, 2022
6 May 14, 2023
11 Mar 19, 2023
10 Mar 25, 2023
15 Nov 8, 2023
80 Dec 26, 2022
4.6k Jan 1, 2023
632 Jan 4, 2023
4 Aug 25, 2022
4.8k Jan 7, 2023
4 Dec 28, 2022
11 Jan 25, 2023
6 Nov 13, 2023
1 Oct 21, 2021
3 Feb 6, 2022
45 Dec 11, 2022
2 Dec 31, 2022
6 Dec 19, 2022