repository·main·Indexed 10 days ago
https://github.com/orhun/git-cliffA high-performance, highly customizable changelog generator that automates the creation of changelogs from Git commit history. It leverages conventional commits, regex-powered custom parsers, and customizable templates. Version 2.13.1 supports hierarchical configuration via TOML, environment variables, or project manifests, and integrates with remote hosting providers like GitHub, GitLab, Gitea, Bitbucket, and Azure DevOps.
In recent versions, git-cliff has improved automatic discovery for monorepos. When running from a sub-directory within a Git repository:
include-path is automatically set to the current directory.This eliminates the need to manually specify --include-path and --repository when working in sub-packages.
The determined version bump type is available in the release context as {{ bump_type }}. You can use this to include specific text or sections in your changelog only when a certain type of release occurs.
Available bump types:
majorminorpatch{% if bump_type == "major" %}
- This is a major release!
{% endif %}The Gitea integration injects specific data into the template context.
You can access the repository owner and name using the remote.gitea object:
{
"gitea": {
"owner": "orhun",
"repo": "git-cliff"
}
}Each commit object contains a remote nested object with Gitea-specific metadata:
{
"id": "...",
"message": "...",
"remote": {
"username": "orhun",
"pr_title": "some things have changed",
"pr_number": 420,
"pr_labels": ["rust"],
"is_first_time": false
}
}For each release, a gitea.contributors list is available containing metadata for all contributors in that release:
{
"gitea": {
"contributors": [
{
"username": "orhun",
"pr_title": "some things have changed",
"pr_number": 420,
"pr_labels": ["rust"],
"is_first_time": true
}
]
}
}The template context includes a merge_commit boolean field. You can use this within a Jinja2 filter to exclude merge commits from specific groups in your changelog.
{% for group, commits in commits |
filter(attribute="merge_commit", value=false) |
group_by(attribute="group") %}
### {{ group | upper_first }}
{% for commit in commits %}
- {{ commit.message | upper_first }}\
{% endfor %}
{% endfor %}0.x.y), you may want to preserve the leading zero even during breaking changes to signal API stability levels. To implement this behavior, you must customize the bumping rules in your git-cliff configuration file using the bump configuration section.When offline is enabled, git-cliff ensures no external network requests are made, even if a remote is configured. This is useful for restricted environments or when running --bumped-version.
You can enable offline mode via:
offline = true--offlineGIT_CLIFF_OFFLINEThe Azure DevOps integration injects specific data into the template context, allowing you to include usernames, PR numbers, and contributor lists in your changelog.
You can access the remote repository information using the remote.azure_devops object:
{
"azure_devops": {
"owner": "myorg/myproject",
"repo": "myrepo"
}
}Each commit object contains a remote nested object with the following fields:
username: The Azure DevOps username.pr_title: The title of the associated Pull Request.pr_number: The Pull Request number.pr_labels: A list of labels associated with the PR.is_first_time: A boolean indicating if this is the user's first contribution.Example Template Usage:
{% for commit in commits %}
* {{ commit.message | split(pat="\n") | first | trim }}
{% if commit.remote.username %} by @{{ commit.remote.username }}{%- endif %}
{% if commit.remote.pr_number %} in #{{ commit.remote.pr_number }}{%- endif %}
{%- endfor %}For each release, the azure_devops.contributors list is available, containing objects for each contributor:
usernamepr_titlepr_numberpr_labelsis_first_timeExample Template Usage (First-time contributors):
{% for contributor in azure_devops.contributors | filter(attribute="is_first_time", value=true) %}
* @{{ contributor.username }} made their first contribution in #{{ contributor.pr_number }}
{%- endfor %}{
"id": "8edec7fd50f703811d55f14a3c5f0fd02b43d9e7",
"message": "refactor(config): remove unnecessary newline from configs\n",
"group": "🚜 Refactor",
"remote": {
"username": "orhun",
"pr_title": "some things have changed",
"pr_number": 420,
"pr_labels": ["enhancement"],
"is_first_time": false
}
}You can use Gitea integration to pull repository-specific data like usernames and pull request numbers into your changelog templates. This allows for more detailed contributor lists and commit descriptions.
Available variables:
${{ commit.gitea.username }} or ${{ contributor.username }}${{ gitea.contributors }}${{ commit.gitea.pr_number }} or ${{ contributor.pr_number }}## What's Changed
- feat(commit): add merge_commit flag to the context by @orhun in #389
- test(fixture): add test fixture for bumping version by @orhun in #360
## New Contributors
- @someone made their first contribution in #360
- @cliffjumper made their first contribution in #389The GitLab integration injects specific data into the template context, allowing you to include GitLab-specific metadata in your changelog.
Access the repository owner and name via remote.gitlab:
{
"gitlab": {
"owner": "orhun",
"repo": "git-cliff"
}
}Example usage for a tag URL:
https://gitlab.com/{{ remote.gitlab.owner }}/{{ remote.gitlab.repo }}/-/tags/{{ version }}
Note: In GitLab CI, you can use {{ get_env(name="CI_PROJECT_URL") }} instead.
Each commit object contains a remote nested object:
username: GitLab usernamepr_title: Title of the Merge Requestpr_number: Merge Request numberpr_labels: List of labels on the MRis_first_time: Boolean indicating if this is the user's first contributionExample template snippet:
{% for commit in commits %}
* {{ commit.message | split(pat="\n") | first | trim }}
{% if commit.remote.username %} by @{{ commit.remote.username }}{%- endif %}
{% if commit.remote.pr_number %} in #{{ commit.remote.pr_number }}{%- endif %}
{%- endfor %}For each release, a gitlab.contributors list is available containing objects for each contributor:
{
"gitlab": {
"contributors": [
{
"username": "orhun",
"pr_title": "some things have changed",
"pr_number": 420,
"pr_labels": ["rust"],
"is_first_time": true
}
]
}
}Example to list new contributors:
{% for contributor in gitlab.contributors | filter(attribute="is_first_time", value=true) %}
* @{{ contributor.username }} made their first contribution in #{{ contributor.pr_number }}
{%- endfor %}The commit processing pipeline follows this order:
This order allows you to use commit preprocessors to split a single commit into multiple conventional commits before they are parsed.
git-cliff automatically detects configuration files based on their presence in the project root.
cliff.toml exists, it is used (even if a project manifest like Cargo.toml is also present).cliff.toml is absent but a project manifest (e.g., Cargo.toml) contains a [workspace.metadata.git-cliff.changelog] table, git-cliff will use the configuration from that manifest.For Rust projects, you can simply run git cliff instead of specifying --config Cargo.toml if you have configured the metadata table.
$ git cliff
# is same as
$ git cliff --config Cargo.toml