https://github.com/orhun/git-cliff

Skip to content
 
Sign up

  * Why GitHub?
    Features -
      + Mobile -
      + Actions -
      + Codespaces -
      + Packages -
      + Security -
      + Code review -
      + Issues -
      + Integrations -
      + GitHub Sponsors -
      + Customer stories-
  * Team
  * Enterprise
  * Explore
      + Explore GitHub -

    Learn and contribute

      + Topics -
      + Collections -
      + Trending -
      + Learning Lab -
      + Open source guides -

    Connect with others

      + The ReadME Project -
      + Events -
      + Community forum -
      + GitHub Education -
      + GitHub Stars program -
  * Marketplace
  * Pricing
    Plans -
      + Compare plans -
      + Contact Sales -
      + Education -

[                    ] 

  *  
    #
    In this repository All GitHub |
    Jump to |

  * No suggested jump to results

  *  
    #
    In this repository All GitHub |
    Jump to |
  *  
    #
    In this user All GitHub |
    Jump to |
  *  
    #
    In this repository All GitHub |
    Jump to |

Sign in
Sign up
{{ message }}

orhun / git-cliff

  * Sponsor

    Sponsor orhun/git-cliff

  * Notifications
  * Star 1.1k
  * Fork 8

A highly customizable Changelog Generator that follows Conventional
Commit specifications [?][?]

GPL-3.0 License
1.1k stars 8 forks
Star
Notifications

  * Code
  * Issues 0
  * Pull requests 1
  * Actions
  * Security
  * Insights

More

  * Code
  * Issues
  * Pull requests
  * Actions
  * Security
  * Insights

main
Switch branches/tags
[                    ]
Branches Tags
Could not load branches
Nothing to show
{{ refName }} default View all branches
Could not load tags
Nothing to show
{{ refName }} default
View all tags
1 branch 35 tags
Code

  *  
    Clone
    HTTPS GitHub CLI
    [https://github.com/o]

    Use Git or checkout with SVN using the web URL.

    [gh repo clone orhun/]

    Work fast with our official CLI. Learn more.

  * Open with GitHub Desktop
  * Download ZIP

Launching GitHub Desktop

If nothing happens, download GitHub Desktop and try again.

Go back

Launching GitHub Desktop

If nothing happens, download GitHub Desktop and try again.

Go back

Launching Xcode

If nothing happens, download Xcode and try again.

Go back

Launching Visual Studio Code

Your codespace will open once ready.

There was a problem preparing your codespace, please try again.

Latest commit

@orhun
orhun docs(readme): update installation instructions for Arch Linux
...
8fb18b7 Sep 4, 2021
docs(readme): update installation instructions for Arch Linux
8fb18b7

Git stats

  * 263 commits

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
.github
fix(cd): change the config file location for crates.io release
Aug 20, 2021
config
chore(config): move cliff.toml to config/
Aug 17, 2021
examples
fix(template): use 7 digits for short SHA
Aug 2, 2021
git-cliff-core
chore(release): prepare for v0.2.6
Sep 4, 2021
git-cliff
chore(release): prepare for v0.2.6
Sep 4, 2021
.dockerignore
chore(docker): add Dockerfile
Jun 11, 2021
.editorconfig
chore(project): update .editorconfig about shell scripts
Jun 21, 2021
.gitignore
chore(git): remove etc directory from .gitignore
Aug 7, 2021
CHANGELOG.md
chore(release): prepare for v0.2.6
Sep 4, 2021
CODE_OF_CONDUCT.md
chore(project): rename
May 29, 2021
CONTRIBUTING.md
docs(contributing): add CONTRIBUTING.md
Jun 28, 2021
Cargo.lock
chore(release): prepare for v0.2.6
Sep 4, 2021
Cargo.toml
chore(project): rename
May 29, 2021
Dockerfile
chore(docker): bump cargo-chef version in Dockerfile
Sep 4, 2021
LICENSE
Initial commit
May 10, 2021
README.md
docs(readme): update installation instructions for Arch Linux
Sep 4, 2021
RELEASE.md
chore(release): set the new version in release script
Jun 29, 2021
codecov.yml
chore(project): add codecov.yml
Jun 7, 2021
release.sh
chore(release): show the committed changes before creating a tag
Aug 20, 2021
rustfmt.toml
chore(fmt): remove normalize_comments from rustfmt.toml
Jun 4, 2021
View code
[                    ]
About Installation From crates.io Using pacman Binary Releases Usage
Command Line Arguments Examples Docker GitHub Action Configuration
File changelog header body trim footer git conventional_commits
commit_parsers filter_commits tag_pattern skip_tags 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 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 [1.0.0] - 2021-07-18 Bug Fixes Args
Documentation Example Project Features Parser Keep a Changelog
Changelog [unreleased] Added Changed [1.0.1] - 2021-07-18 Added
Changed [1.0.0] - 2021-07-18 Added Fixed Similar Projects License
Copyright

README.md

             [121790699-8808dc80-cbea-11eb-8ab6-2fb6b08]
               [6874747073] [6874747073] [6874747073]
         [6874747073] [6874747073] [6874747073] [6874747073]

 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.

preview

Table of Contents

  * About
  * Installation
      + From crates.io
      + Using pacman
      + Binary Releases
  * Usage
      + Command Line Arguments
      + Examples
  * Docker
  * GitHub Action
  * Configuration File
      + changelog
          o header
          o body
          o trim
          o footer
      + git
          o conventional_commits
          o commit_parsers
          o filter_commits
          o tag_pattern
          o skip_tags
  * Templating
      + Context
          o Conventional Commits
              # Breaking Changes
          o Non-Conventional Commits
      + Syntax
      + Examples
          o Basic
          o Detailed
          o Scoped
          o Keep a Changelog
  * Similar Projects
  * License
  * Copyright

 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 <PATH>        Sets the configuration file [env: CONFIG=]  [default: cliff.toml]
-w, --workdir <PATH>       Sets the working directory [env: WORKDIR=]
-r, --repository <PATH>    Sets the repository to parse commits from [env: REPOSITORY=]
-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]

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

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

<type>[optional scope]: <description>

[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,

<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
    }
  ],
  "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

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

 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

 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

 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 (c) 2021, git-cliff contributors

About

A highly customizable Changelog Generator that follows Conventional
Commit specifications [?][?]

Topics

rust generator changelog semver commit conventional-changelog 
keepachangelog changelog-generator conventional-commits

Resources

Readme

License

GPL-3.0 License

Releases 35

 
Release v0.2.6 Latest
Sep 4, 2021
+ 34 releases

Sponsor this project

  * patreon patreon.com/orhunp
  * https://orhun.dev/donate/xmr

Packages 1

 

Contributors 2

  * @orhun orhun Orhun Parmaksiz
  * @kondanta kondanta Taylan Dogan

Languages

  * Rust 94.8%
  * Shell 2.9%
  * Dockerfile 2.3%

  * (c) 2021 GitHub, Inc.
  * Terms
  * Privacy
  * Security
  * Status
  * Docs

 

  * Contact GitHub
  * Pricing
  * API
  * Training
  * Blog
  * About

You can't perform that action at this time.
You signed in with another tab or window. Reload to refresh your
session. You signed out in another tab or window. Reload to refresh
your session.