mirror of https://github.com/orhun/git-cliff.git synced 2024-12-15 18:44:21 +03:00

Orhun Parmaksız 848d8a587e

2022-01-29 18:53:26 +03:00

32 KiB

Raw Blame History

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

About
Installation
Usage
- Command Line Arguments
- Examples
Docker
GitHub Action
GitLab CI/CD
Configuration File
- changelog
  - header
  - body
  - trim
  - footer
- git
Templating
Similar Projects
License
Copyright

Installation

Packaging status

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.

* Release tarballs are signed with the following PGP key: 1D2D410A741137EBC544826F4A92FA17B6619297

Build from source

Linux dependencies: zlib

# binary will be located at `target/release/git-cliff`
CARGO_TARGET_DIR=target cargo build --release

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
    --current       Processes the commits that belong to the current tag
-u, --unreleased    Processes the commits that do not belong to a tag
    --topo-order    Sorts the tags topologically
-h, --help          Prints help information
-V, --version       Prints version information

Options:

-c, --config <PATH>               Sets the configuration file [env: CONFIG=]  [default: cliff.toml]
-w, --workdir <PATH>              Sets the working directory [env: WORKDIR=]
-r, --repository <PATH>           Sets the git repository [env: REPOSITORY=]
    --include-path <PATTERN>...   Sets the path to include related commits [env: INCLUDE_PATH=]
    --exclude-path <PATTERN>...   Sets the path to exclude related commits [env: EXCLUDE_PATH=]
    --with-commit <MSG>...        Sets custom commit messages to include in the changelog [env: WITH_COMMIT=]
-p, --prepend <PATH>              Prepends entries to the given changelog file [env: PREPEND=
-o, --output <PATH>               Writes output to the given file [env: OUTPUT=]
-t, --tag <TAG>                   Sets the tag for the latest version [env: TAG=]
-b, --body <TEMPLATE>             Sets the template for the changelog body [env: TEMPLATE=]
-s, --strip <PART>                Strips the given parts from the changelog [possible values: header, footer, all]
    --sort <sort>                 Sets sorting of the commits inside sections [default: oldest] [possible values: oldest, newest]

Args:

<RANGE>    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

Generate a changelog for a certain part of git history:

# only takes the latest tag into account
# (requires at least 2 tags)
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 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"

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

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.

GitLab CI/CD

It is possible to generate changelogs using GitLab CI/CD.

This minimal example creates artifacts that can be used on another job.

- changelog:
    image:
      name: orhunp/git-cliff:latest
      entrypoint: [""]
    variables:
      GIT_STRATEGY: clone # clone entire repo instead of reusing workspace
      GIT_DEPTH: 0 # avoid shallow clone to give cliff all the info it needs
    stage: doc
    script:
      - git-cliff -r . > CHANGELOG.md
    artifacts:
      paths:
        - CHANGELOG.md

Please note that the stage is doc and has to be changed accordingly to your need.

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/<user>/.config/git-cliff/cliff.toml
on Windows: C:\Users\<user>\AppData\Roaming\git-cliff\cliff.toml
on macOS: /Users/<user>/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 = "<!-- generated by git-cliff -->"

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
filter_unconventional = 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"
ignore_tags = ""
topo_order = false
sort_commits = "oldest"
link_parsers = [
    { pattern = "#(\\d+)", href = "https://github.com/orhun/git-cliff/issues/$1"},
    { pattern = "RFC(\\d+)", text = "ietf-rfc$1", href = "https://datatracker.ietf.org/doc/html/rfc$1"},
]

conventional_commits

If set to true, commits are parsed 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:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

e.g. feat(parser): add ability to parse arrays

filter_unconventional

If set to true, commits that are not conventional are excluded. This option can be used to generate changelogs with conventional and unconvential commits mixed together. For example:

conventional_commits = true
filter_unconventional = false
commit_parsers = [
  { message = ".*", group = "Other", default_scope = "other"},
]

With the configuration above, conventional commits are parsed as usual and unconventional commits will be also included in the changelog as "Other".

To completely exclude unconventional commits from the changelog:

# default behaviour
conventional_commits = true
filter_unconventional = true

To include any type of commit in the changelog without parsing:

conventional_commits = false
filter_unconventional = false

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".
{ message = "^doc", group = "Documentation", default_scope = "other"},
- If the commit starts with "doc", group the commit as "Documentation" and set the default scope to "other". (e.g. docs: xyz will be processed as docs(other): xyz)

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.

ignore_tags

A regex for ignore processing the matched tags.

While skip_tags drop commits from the changelog, ignore_tags include ignored commits into the next tag.

topo_order

If set to true, tags are processed in topological order instead of chronological.

This can also be achieved by using the --topo-order command line flag.

sort_commits

Sort the commits inside sections by specified order.

Possible values:

oldest
newest

This can also be achieved by specifying the --sort command line argument.

link_parsers

An array of link parsers for extracting external references, and turning them into URLs, using regex.

Examples:

{ pattern = "#(\\d+)", href = "https://github.com/orhun/git-cliff/issues/$1"}
- Extract all GitLab issues and PRs and generate URLs linking to them. The link text will be the matching pattern.
{ pattern = "RFC(\\d+)", text = "ietf-rfc$1", href = "https://datatracker.ietf.org/doc/html/rfc$1"},
- Extract mentions of IETF RFCs and generate URLs linking to them. It also rewrites the text as "ietf-rfc...".

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,

<type>[scope]: <description>

[body]

[footer(s)]

following context is generated to use for templating:

{
  "version": "v0.1.0-rc.21",
  "commits": [
    {
      "id": "e795460c9bb7275294d1fa53a9d73258fb51eb10",
      "group": "<type> (overrided by commit_parsers)",
      "scope": "[scope]",
      "message": "<description>",
      "body": "[body]",
      "footers": ["[footer]", "[footer]"],
      "breaking_description": "<description>",
      "breaking": false,
      "conventional": true,
      "links": [{"text": "(set by link_parsers)", "href": "(set by link_parsers)"}]
    }
  ],
  "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)",
      "scope": "(overrided by commit_parsers)",
      "message": "(full commit message including description, footers, etc.)",
      "conventional": false,
      "links": [{"text": "(set by link_parsers)", "href": "(set by link_parsers)"}]
    }
  ],
  "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

<!-- generated by git-cliff -->

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

Minimal

Raw Output

## [unreleased]
### Feat
- Support multiple file formats
- Use cache while fetching pages

## [1.0.1] - 2021-07-18
### Chore
- Add release script

### Refactor
- Expose string functions

## [1.0.0] - 2021-07-18
### Docs
- Add README.md
- [**breaking**] Add tested usage example

### Feat
- Add ability to parse arrays

### Fix
- Rename help argument due to conflict

Rendered Output

[unreleased]

Feat

Support multiple file formats
Use cache while fetching pages

[1.0.1] - 2021-07-18

Chore

Add release script

Refactor

Expose string functions

[1.0.0] - 2021-07-18

Docs

Add README.md
[breaking] Add tested usage example

Feat

Add ability to parse arrays

Fix

Rename help argument due to conflict

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))

<!-- generated by git-cliff -->

Rendered Output

Changelog

All notable changes to this project will be documented in this file.

[unreleased]

Features

Support multiple file formats (a9d4050)
Use cache while fetching pages (df6aef4)

[1.0.1] - 2021-07-18

ad27b43...06412ac

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

Add README.md (81fbc63)
Add tested usage example (ad27b43)

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

<!-- generated by git-cliff -->

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

Scoped (Sorted)

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
  - **BREAKING**: add tested usage example
- *(project)* Add README.md

### Features

- *(parser)* Add ability to parse arrays

<!-- generated by git-cliff -->

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
- BREAKING: 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

<!-- generated by git-cliff -->

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

Unconventional

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 ✔️

### Other (unconventional)

- Initial commit ❌

<!-- generated by git-cliff -->

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 ✔️

Other (unconventional)

Initial commit ❌

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)

32 KiB Raw Blame History

About

Installation

From crates.io

Using pacman

Binary releases

Build from source

Usage

Command Line Arguments

Examples

Docker

GitHub Action

GitLab CI/CD

Configuration File

changelog

header

body

trim

footer

git

conventional_commits

filter_unconventional

commit_parsers

filter_commits

tag_pattern

skip_tags

ignore_tags

topo_order

sort_commits

link_parsers

Templating

Context

Conventional Commits

Breaking Changes

Non-Conventional Commits

Syntax

Examples

Basic

Changelog

[unreleased]

Features

[1.0.1] - 2021-07-18

Miscellaneous Tasks

Refactor

[1.0.0] - 2021-07-18

Bug Fixes

Documentation

Features

Minimal

[unreleased]

Feat

[1.0.1] - 2021-07-18

Chore

Refactor

[1.0.0] - 2021-07-18

Docs

Feat

Fix

Detailed

Changelog

[unreleased]

Features

[1.0.1] - 2021-07-18

Miscellaneous Tasks

Refactor

[1.0.0] - 2021-07-18

Bug Fixes

Documentation

Features

Scoped

Changelog

[unreleased]

Features

Cache

Config

[1.0.1] - 2021-07-18

Miscellaneous Tasks

Release

Refactor

Parser

32 KiB

Raw Blame History