### Set up and Run git-cliff in GitHub Actions

Source: https://git-cliff.org/docs/github-actions/setup-git-cliff

This example demonstrates how to use the setup-git-cliff action to install the git-cliff binary and then run it to generate changelogs.

```yaml
- name: Check out repository
  uses: actions/checkout@v3
  with:
    fetch-depth: 0

- name: Set up git-cliff
  uses: kenji-miyake/setup-git-cliff@v1

- name: Run git-cliff
  run: git cliff

```

--------------------------------

### Install and Use git-cliff in GitHub Actions

Source: https://git-cliff.org/docs/github-actions/taiki-e-install-action

This example demonstrates how to check out a repository, install git-cliff using the taiki-e/install-action, and then generate a changelog.

```yaml
- name: Check out repository  
  uses: actions/checkout@v3  
  with:  
    fetch-depth: 0  
  
- name: Install git-cliff  
  uses: taiki-e/install-action@git-cliff  
  
- name: Generate changelog  
  run: git-cliff  

```

--------------------------------

### Install git-cliff from Crates.io

Source: https://git-cliff.org/docs/installation/crates-io

Use this command to install the latest stable version of git-cliff from crates.io.

```bash
cargo install git-cliff  

```

--------------------------------

### GitLab Authentication Example

Source: https://git-cliff.org/docs/integration/gitlab

Example of how to authenticate with GitLab using the GITLAB_TOKEN environment variable and the --gitlab-repo argument when running the git-cliff command.

```bash
GITLAB_TOKEN="***" git cliff --gitlab-repo "orhun/git-cliff"

```

--------------------------------

### Install git-cliff on Alpine Linux

Source: https://git-cliff.org/docs/installation/alpine-linux

Use this command to install git-cliff on Alpine Linux after enabling the community repository.

```bash
apk add git-cliff  

```

--------------------------------

### Install git-cliff using emerge

Source: https://git-cliff.org/docs/installation/gentoo-linux

Use this command to install git-cliff on Gentoo Linux. Ensure your system architecture is supported.

```bash
emerge git-cliff  

```

--------------------------------

### Install git-cliff using Cargo

Source: https://git-cliff.org/docs

Use this command to install the git-cliff tool via the Cargo package manager.

```bash
cargo install git-cliff
```

--------------------------------

### Azure DevOps Authentication Example

Source: https://git-cliff.org/docs/integration/azure-devops

Example of running git-cliff with Azure DevOps integration, specifying the repository and using an environment variable for the access token.

```bash
AZURE_DEVOPS_TOKEN="***" git cliff --azure-devops-repo "myorg/myproject/myrepo"

```

--------------------------------

### Install git-cliff with Homebrew

Source: https://git-cliff.org/docs/installation/homebrew

Use this command to install the git-cliff tool on macOS via Homebrew.

```bash
brew install git-cliff
```

--------------------------------

### Install git-cliff on Arch Linux

Source: https://git-cliff.org/docs/installation/arch-linux

Use the pacman package manager to install git-cliff from the official Arch Linux repositories.

```bash
pacman -S git-cliff  

```

--------------------------------

### Install git-cliff using WinGet

Source: https://git-cliff.org/docs/installation/winget

Use this command in your Windows terminal to install git-cliff via the WinGet package manager.

```bash
winget install git-cliff  
```

--------------------------------

### Install Latest Git Version of git-cliff

Source: https://git-cliff.org/docs/installation/crates-io

Install the most recent version directly from the git repository.

```bash
cargo install --git https://github.com/orhun/git-cliff  

```

--------------------------------

### Install git-cliff with pip

Source: https://git-cliff.org/docs/installation/pypi

Use this command to install git-cliff if you are a Python user and want to manage it via pip.

```bash
pip install git-cliff  

```

--------------------------------

### Configure GitLab Remote Example

Source: https://git-cliff.org/docs/configuration/remote

A complete configuration example for a GitLab remote, including API URL and token. Set offline to false to enable remote interactions.

```toml
[remote]
offline = false

[remote.gitlab]
owner = "archlinux"
repo = "arch-repro-status"
api_url = "https://gitlab.archlinux.org/api/v4"
token = "deadbeef"
native_tls = false
```

--------------------------------

### Install git-cliff using MacPorts

Source: https://git-cliff.org/docs/installation/macports

Use this command to install git-cliff on macOS if you have MacPorts installed. Ensure MacPorts is up-to-date before running the installation command.

```bash
sudo port install git-cliff  

```

--------------------------------

### Example GitHub Changelog Output

Source: https://git-cliff.org/docs/integration/github

This is an example of the changelog output generated using the `github.toml` configuration. It includes sections for 'What's Changed' and 'New Contributors'.

```markdown
## 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 #389  
  
<!-- generated by git-cliff -->  

```

--------------------------------

### Install git-cliff Temporarily with nix-shell

Source: https://git-cliff.org/docs/installation/nix

Use this command to temporarily install git-cliff in your current shell environment. This is useful for trying out the tool without a permanent installation.

```bash
nix-shell -p git-cliff  
```

--------------------------------

### GitHub Remote URL Example

Source: https://git-cliff.org/docs/integration/github

An example of how to use the GitHub remote context in a template to construct a comparison URL between versions.

```template
https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }}/compare/{{ previous.version }}...{{ version }}

```

--------------------------------

### Changelog Configuration Example

Source: https://git-cliff.org/docs/configuration/changelog

This TOML snippet shows a complete configuration for generating a changelog, including header, body template, footer, whitespace trimming, and postprocessors.

```toml
[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 -->"
postprocessors = [{ pattern = "foo", replace = "bar"}]

```

--------------------------------

### Install git-cliff with Specific Features

Source: https://git-cliff.org/docs/installation/crates-io

Install git-cliff with default features disabled, but enable the 'update-informer' feature for release notifications.

```bash
cargo install git-cliff --no-default-features --features update-informer  

```

--------------------------------

### Install git-cliff Globally with Mise

Source: https://git-cliff.org/docs/installation/mise

Use this command to install the latest version of git-cliff globally, making it available across your system via mise.

```bash
mise use -g git-cliff@latest  

```

--------------------------------

### Template Example for Gitea First-Time Contributors

Source: https://git-cliff.org/docs/integration/gitea

Filter and list contributors who made their first contribution to the project, displaying their username and the associated pull request number.

```handlebars
{% for contributor in gitea.contributors | filter(attribute="is_first_time", value=true) %}
  * @{{ contributor.username }} made their first contribution in #{{ contributor.pr_number }}
{%- endfor -%}

```

--------------------------------

### Install git-cliff globally

Source: https://git-cliff.org/docs/installation/binary-releases

Move the git-cliff binary to /usr/local/bin/ to make it accessible from any terminal location.

```bash
sudo mv git-cliff /usr/local/bin/  
```

--------------------------------

### Azure DevOps Changelog Example

Source: https://git-cliff.org/docs/integration/azure-devops

This example demonstrates the output of a changelog generated with Azure DevOps integration, adhering to the Keep a Changelog format and Semantic Versioning. It includes sections for added, fixed, and changed features, along with version links.

```markdown
# 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).  
  
## [1.0.0] - 2024-01-15  
  
### Added  
- feat: add new feature by @orhun in #123  
- feat: support Azure DevOps integration by @contributor in #456  
  
### Fixed  
- fix: resolve bug in parser by @orhun in #789  
- test: add test coverage for edge cases by @someone in #101  
  
### Changed  
- refactor: improve performance by @cliffjumper in #202  
  
[1.0.0]: https://dev.azure.com/myorg/myproject/_git/myrepo/branchCompare?baseVersion=GTv0.9.0&targetVersion=GTv1.0.0  
  
<!-- generated by git-cliff -->  

```

--------------------------------

### Configure GitHub Remote in Configuration File

Source: https://git-cliff.org/docs/integration/github

Specify the GitHub owner, repository, and token in the configuration file for remote setup.

```toml
[remote.github]
owner = "orhun"
repo = "git-cliff"
token = "***"

```

--------------------------------

### Install git-cliff Permanently with nix-env

Source: https://git-cliff.org/docs/installation/nix

Use this command to permanently install git-cliff. Be aware that this modifies your local package profile and requires manual updates.

```bash
nix-env -iA nixpkgs.git-cliff  
```

--------------------------------

### Formatted First-Time Contributors List

Source: https://git-cliff.org/docs/integration/gitlab

Example output of a changelog section listing contributors who made their first contribution to the project, formatted using the GitLab contributors context.

```markdown
- @orhun made their first contribution in #420
- @cliffjumper made their first contribution in #999

```

--------------------------------

### Example: Custom Minor Increment

Source: https://git-cliff.org/docs/configuration/bump

Demonstrates how a commit matching 'more' increments the version to 0.2.0 from 0.1.0.

```bash
git-cliff --bumped-version 
  
0.2.0  

```

--------------------------------

### Run git-cliff with npx

Source: https://git-cliff.org/docs/installation/npm

Execute the latest version of git-cliff directly from NPM without installation.

```bash
npx git-cliff@latest  

```

--------------------------------

### Example: Custom Major Increment

Source: https://git-cliff.org/docs/configuration/bump

Demonstrates how a commit matching 'major' increments the version to 1.0.0 from 0.1.0.

```bash
git-cliff --bumped-version 
  
1.0.0  

```

--------------------------------

### Install git-cliff Without Default Features

Source: https://git-cliff.org/docs/installation/crates-io

Install git-cliff while disabling all default features. This is useful if you want to selectively enable features.

```bash
cargo install git-cliff --no-default-features  

```

--------------------------------

### Install git-cliff globally with pixi

Source: https://git-cliff.org/docs/installation/conda-forge

Use this command to install git-cliff globally on your system using pixi and the conda-forge channel. This makes the git-cliff executable available in your PATH.

```bash
pixi global install git-cliff  

```

--------------------------------

### Configure git-cliff in pyproject.toml

Source: https://git-cliff.org/docs/integration/python

Example of `pyproject.toml` configuration for git-cliff, including changelog and git settings. This is used for Python projects.

```toml
name = "..."  
  
[project]  
dependencies = []  
  
[tool.git-cliff.changelog]  
header = "All notable changes to this project will be documented in this file."  
body = "..."  
footer = "<!-- generated by git-cliff -->"  
# see [changelog] section for more keys  
  
[tool.git-cliff.git]  
conventional_commits = true  
commit_parsers = []  
filter_commits = false  
# see [git] section for more keys  


```

--------------------------------

### Sample Git History

Source: https://git-cliff.org/docs/templating/examples

A sample Git commit history used to generate changelog examples.

```git
* 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  

```

--------------------------------

### Example: No Version Increment

Source: https://git-cliff.org/docs/configuration/bump

Shows that commits matching the 'no_increment_regex' do not change the version from 0.1.0.

```bash
git-cliff --bumped-version 
  
0.1.0  

```

--------------------------------

### Conventional Commit Message Examples

Source: https://git-cliff.org/docs

Examples of commit messages following the Conventional Commits specification. This format helps git-cliff generate structured changelogs.

```git
fix(parser): handle empty commit messages gracefully
feat(cli): add support for --dry-run flag
refactor(core)!: change internal API to use async/await
```

--------------------------------

### Run git-cliff with nix run (New CLI)

Source: https://git-cliff.org/docs/installation/nix

This command allows you to run git-cliff directly using the new experimental CLI without a permanent installation.

```bash
nix run nixpkgs#git-cliff  
```

--------------------------------

### Conventional Commits Specification Example

Source: https://git-cliff.org/docs/configuration/git

Illustrates the structure of a conventional commit message, including type, scope, description, body, and footers.

```markdown
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

```

--------------------------------

### Template Example for Gitea Commit Links

Source: https://git-cliff.org/docs/integration/gitea

Iterate through commits and conditionally display Gitea usernames and pull request numbers. Requires the 'gitea' feature flag.

```handlebars
{% 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 -%}

```

--------------------------------

### Get Next Semantic Version

Source: https://git-cliff.org/docs/usage/bump-version

Calculates and prints the next semantic version to standard output. Useful for scripting or CI/CD pipelines.

```bash
git cliff --bumped-version  

```

--------------------------------

### Configure git-cliff in Cargo.toml

Source: https://git-cliff.org/docs/integration/rust

Use the `[package.metadata.git-cliff.<section>]` tables in Cargo.toml to configure git-cliff for a Rust project. This example shows configuration for the changelog body and git settings.

```toml
[package]
name = "..."

[dependencies]
# ...

[package.metadata.git-cliff.changelog]
header = "All notable changes to this project will be documented in this file."
body = "..."
footer = "<!-- generated by git-cliff -->"
# see [changelog] section for more keys

[package.metadata.git-cliff.git]
conventional_commits = true
commit_parsers = []
filter_commits = false
# see [git] section for more keys

```

--------------------------------

### Custom Processing Order

Source: https://git-cliff.org/docs/configuration/git

Defines a custom pipeline for processing commits. This example shows the default order, but it can be rearranged to alter processing logic.

```toml
[git]
processing_order = [
    "commit_preprocessors",
    "split_commits",
    "conventional_commits",
    "commit_parsers",
    "link_parsers",
]

```

--------------------------------

### Override git-cliff footer using environment variable

Source: https://git-cliff.org/docs/configuration

Use environment variables to override configuration elements. This example shows how to set the footer.

```bash
export GIT_CLIFF__CHANGELOG__FOOTER="<!-- footer from env -->"
```

--------------------------------

### Footer Example

Source: https://git-cliff.org/docs/templating/context

Footers in conventional commits are key-value pairs that provide structured information. They are parsed into a 'footers' array within the commit object.

```text
* `Signed-off-by: User Name <user.email@example.com>`
* `Reviewed-by: User Name <user.email@example.com>`
* `Fixes #1234`
* `BREAKING CHANGE: breaking change description`

```

--------------------------------

### Azure DevOps Remote URL Template

Source: https://git-cliff.org/docs/integration/azure-devops

Example of using the Azure DevOps remote context in a URL template to construct a branch comparison link.

```html
https://dev.azure.com/{{ remote.azure_devops.owner }}/_git/{{ remote.azure_devops.repo }}/branchCompare?baseVersion=GT{{ previous.version }}&targetVersion=GT{{ version }}
```

--------------------------------

### Initialize with a Built-in Template

Source: https://git-cliff.org/docs/usage/initializing

Create the `cliff.toml` configuration file using one of the available built-in templates by specifying the template name.

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

--------------------------------

### Generate Default Configuration File

Source: https://git-cliff.org/docs/usage/initializing

Use the `--init` flag to create the default `cliff.toml` configuration file.

```bash
# create cliff.toml 
git cliff --init
```

--------------------------------

### Formatted Commit Entries with GitLab Info

Source: https://git-cliff.org/docs/integration/gitlab

Example output of changelog entries formatted using the GitLab commit context, showing commit messages attributed to authors and linked to pull request numbers.

```markdown
- feat(commit): add merge_commit flag to the context by @orhun in #389
- feat(args): set `CHANGELOG.md` as default missing value for output option by @sh-cho in #354

```

--------------------------------

### Initialize git-cliff Configuration

Source: https://git-cliff.org/docs

Run this command to create a default configuration file (cliff.toml) for git-cliff. Customize this file to match your desired changelog format.

```bash
git-cliff --init
```

--------------------------------

### Get Bumped Version from Context

Source: https://git-cliff.org/docs/usage/bump-version

Retrieves the next bumped version from the git-cliff context and formats it using jq. This is helpful for integrating version bumping into other tools or scripts.

```bash
git cliff --unreleased --bump --context | jq -r .[0].version  

```

--------------------------------

### Create and Process Context Files

Source: https://git-cliff.org/docs/usage/load-context

Use these commands to create a context file, process it to generate a changelog, or process context directly from standard input.

```bash
git cliff --context -o context.json
```

```bash
git cliff --from-context context.json
```

```bash
git cliff --from-context -
```

--------------------------------

### Conventional Commit Context Example

Source: https://git-cliff.org/docs/templating/context

This JSON object represents the context generated for a conventional commit. It includes details like version, message, commit information, author, and statistics.

```json
{
  "version": "v0.1.0-rc.21",
  "message": "The annotated tag message for the release"
  "commits": [
    {
      "id": "e795460c9bb7275294d1fa53a9d73258fb51eb10",
      "group": "<type> (overridden by commit_parsers)",
      "scope": "[scope]",
      "message": "<description>",
      "body": "[body]",
      "footers": [
        {
          "token": "<name of the footer, such as 'Signed-off-by'>",
          "separator": "<the separator between the token and value, such as ':'>",
          "value": "<the value following the separator",
          "breaking": false
        }
      ],
      "breaking_description": "<description>",
      "breaking": false,
      "conventional": true,
      "merge_commit": false,
      "links": [
        { "text": "(set by link_parsers)", "href": "(set by link_parsers)" }
      ],
      "author": {
        "name": "User Name",
        "email": "user.email@example.com",
        "timestamp": 1660330071
      },
      "committer": {
        "name": "User Name",
        "email": "user.email@example.com",
        "timestamp": 1660330071
      },
      "statistics": {
        "files_changed": 1,
        "additions": 1,
        "deletions": 0
      },
      "raw_message": "<type>[scope]: <description>\n[body]\n[footer(s)]"
    }
  ],
  "commit_id": "a440c6eb26404be4877b7e3ad592bfaa5d4eb210 (release commit)",
  "timestamp": 1625169301,
  "repository": "/path/to/repository",
  "commit_range": {
      "from": "(id of the first commit used for this release)",
      "to": "(id of the last commit used for this release)"
  "submodule_commits": {
    "<relative/submodule_path/in/repository>": [
      {
        "id": "c10d0f12e85975bc1e8f41eed693c58eca1894eb",
        "message": "release (#1671)",
        ...
      },
    ],
  },
  "statistics": {
    "commit_count": 1,
    "commits_timespan": 0,
    "conventional_commit_count": 1,
    "links": [
      {
        "text": "#452",
        "href": "https://github.com/orhun/git-cliff/issues/452",
        "count": 1
      }
    ],
    "days_passed_since_last_release": 0
  },
  "bump_type": "minor",
  "previous": {
    "version": "previous release"
  }
}

```

--------------------------------

### Use Remote Configuration File

Source: https://git-cliff.org/docs/usage/initializing

Initialize git-cliff using a configuration file hosted at a remote URL by providing the URL to the `--config-url` option.

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

--------------------------------

### Run git-cliff with GitHub Token and Repository

Source: https://git-cliff.org/docs/integration/github

Execute git-cliff using the GITHUB_TOKEN environment variable and specifying the GitHub repository.

```bash
GITHUB_TOKEN="***" git cliff --github-repo "orhun/git-cliff"

```

--------------------------------

### Download git-cliff (musl-libc)

Source: https://git-cliff.org/docs/installation/binary-releases

Use this command to download the git-cliff binary compiled with musl-libc for x86_64 Linux.

```bash
# version="1.0.0"  
wget "https://github.com/orhun/git-cliff/releases/download/v${version}/git-cliff-${version}-x86_64-unknown-linux-musl.tar.gz"  
```

--------------------------------

### Changelog First-Time Contributor Formatting

Source: https://git-cliff.org/docs/integration/azure-devops

This template iterates through contributors from the Azure DevOps context, specifically highlighting those making their first contribution.

```handlebars
{% for contributor in azure_devops.contributors | filter(attribute="is_first_time", value=true) %}
  * @{{ contributor.username }} made their first contribution in #{{ contributor.pr_number }}
{%- endfor -%}
```

--------------------------------

### Open a Shell with git-cliff using nix shell (New CLI)

Source: https://git-cliff.org/docs/installation/nix

Use this command to open a new shell environment where git-cliff is available. This is an alternative to `nix run` for interactive use.

```bash
nix shell nixpkgs#git-cliff  
```

--------------------------------

### Download git-cliff (glibc)

Source: https://git-cliff.org/docs/installation/binary-releases

Use this command to download the git-cliff binary compiled with glibc for x86_64 Linux.

```bash
# version="1.0.0"  
wget "https://github.com/orhun/git-cliff/releases/download/v${version}/git-cliff-${version}-x86_64-unknown-linux-gnu.tar.gz"  
```

--------------------------------

### Add git-cliff as a dev dependency

Source: https://git-cliff.org/docs/installation/npm

Install git-cliff as a development dependency in your project using Yarn or NPM.

```bash
# with yarn  
yarn add -D git-cliff  
  
# with npm  
npm install git-cliff --save-dev  

```

--------------------------------

### Skip Revert Commits

Source: https://git-cliff.org/docs/configuration/git

Excludes commits that start with 'revert' from the changelog. This is useful for cleaning up revert entries.

```toml
{ message = "^revert", skip = true }
```

--------------------------------

### List First-Time Bitbucket Contributors in Changelog

Source: https://git-cliff.org/docs/integration/bitbucket

Iterate through the Bitbucket contributors and display those marked as making their first contribution, including their username and PR number.

```handlebars
{% for contributor in bitbucket.contributors | filter(attribute="is_first_time", value=true) %}
  * @{{ contributor.username }} made their first contribution in #{{ contributor.pr_number }}
{%- endfor -%}

```

--------------------------------

### Use GitHub Token Argument

Source: https://git-cliff.org/docs/configuration/remote

Provide your GitHub access token via the command-line argument for authentication.

```bash
git cliff --github-token <TOKEN>
```

--------------------------------

### Group Commits by Message Prefix

Source: https://git-cliff.org/docs/configuration/git

Groups commits into the 'Features' category if their message starts with 'feat'. This is a common pattern for conventional commits.

```toml
{ message = "^feat", group = "Features" }
```

--------------------------------

### Use GitHub Repo Argument

Source: https://git-cliff.org/docs/configuration/remote

Specify the GitHub repository directly using the command-line argument.

```bash
git cliff --github-repo orhun/git-cliff
```

--------------------------------

### Generate Custom Configuration File

Source: https://git-cliff.org/docs/usage/initializing

Specify a custom name for the configuration file using the `--config` option along with `--init`.

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

--------------------------------

### Authenticate with Gitea using Environment Variable

Source: https://git-cliff.org/docs/integration/gitea

Provide a Gitea access token via the GITEA_TOKEN environment variable for private repositories. This method is recommended over configuration file storage.

```bash
GITEA_TOKEN="***" git cliff --gitea-repo "orhun/git-cliff"

```

--------------------------------

### Group Fixes with Scoped Names

Source: https://git-cliff.org/docs/configuration/git

Groups commits starting with 'fix' and dynamically includes the scope (e.g., 'fix(api)') in the group name.

```toml
{ message = '^fix\((.*)\)', group = 'Fix (${1})' }
```

--------------------------------

### Run git-cliff from GitHub Container Registry

Source: https://git-cliff.org/docs/docker

Use this command to run the latest git-cliff image from GitHub Container Registry. Mounts the current directory to /app/ within the container.

```bash
docker run -t -v "$(pwd)":/app/ "ghcr.io/orhun/git-cliff/git-cliff:${TAG:-latest}"  
```

--------------------------------

### Generate Basic Changelog

Source: https://git-cliff.org/docs/usage/examples

Generates a changelog at the project's git root directory. This is equivalent to running `git-cliff --config cliff.toml --repository .` or `git-cliff --workdir .`.

```bash
git cliff
```

--------------------------------

### Group Documentation Commits with Default Scope

Source: https://git-cliff.org/docs/configuration/git

Groups commits starting with 'doc' under 'Documentation' and assigns a default scope of 'other' if no scope is specified in the commit.

```toml
{ message = "^doc", group = "Documentation", default_scope = "other" }
```

--------------------------------

### Configure Bitbucket Remote in Configuration File

Source: https://git-cliff.org/docs/integration/bitbucket

Specify the Bitbucket owner, repository, and token in the configuration file for remote integration.

```toml
[remote.bitbucket]
owner = "orhun"
repo = "git-cliff"
token = "***"

```

--------------------------------

### Generate Changelog with a Built-in Template

Source: https://git-cliff.org/docs/usage/initializing

Use a template directly with the `--config` option without creating a configuration file. This generates the changelog using the specified template.

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

--------------------------------

### Override git-cliff ignore_tags using environment variable

Source: https://git-cliff.org/docs/configuration

Use environment variables to override configuration elements. This example shows how to set the ignore_tags pattern for git.

```bash
export GIT_CLIFF__GIT__IGNORE_TAGS="v[0-9]+.[0-9]+.[0-9]+-rc[0-9]+"
```

--------------------------------

### Clone the git-cliff Repository

Source: https://git-cliff.org/docs/installation/build-from-source

Clone the official git-cliff repository to your local machine. This is the first step before building the project.

```bash
git clone https://github.com/orhun/git-cliff
cd git-cliff/
```

--------------------------------

### Generate Changelog and Commit

Source: https://git-cliff.org/docs/usage/adding-commits

This snippet shows the standard process of generating a changelog, staging it, and committing it. The changelog will not include the latest commit message because the commit is created afterward.

```bash
git cliff -o CHANGELOG.md
git add CHANGELOG.md
git commit -m "chore(release): update CHANGELOG.md for 1.0.0"
```

--------------------------------

### Build git-cliff with Profiler Feature

Source: https://git-cliff.org/docs/development/profiling

Builds the git-cliff project with the 'profiler' feature enabled and using the 'bench' build profile. This is the first step to enable performance instrumentation.

```bash
cargo build --profile=bench --features=profiler  

```

--------------------------------

### GitLab Remote Context in Templating

Source: https://git-cliff.org/docs/integration/gitlab

Example of how to use the GitLab remote owner and repository information within changelog templates. This allows for dynamic generation of links to GitLab tags.

```json
{
  "gitlab": {
    "owner": "orhun",
    "repo": "git-cliff"
  }
}

```

```html
https://gitlab.com/{{ remote.gitlab.owner }}/{{ remote.gitlab.repo }}/-/tags/{{ version }}

```

--------------------------------

### Context Structure with Conventional Commits Disabled

Source: https://git-cliff.org/docs/templating/context

When `conventional_commits` is set to `false`, the context omits conventional commit fields and squashes commit messages. This example shows the resulting JSON structure.

```json
{
  "version": "v0.1.0-rc.21",
  "message": "The annotated tag message for the release"
  "commits": [
    {
      "id": "e795460c9bb7275294d1fa53a9d73258fb51eb10",
      "group": "(overridden by commit_parsers)",
      "scope": "(overridden by commit_parsers)",
      "message": "(full commit message including description, footers, etc.)",
      "conventional": false,
      "merge_commit": false,
      "links": [
        { "text": "(set by link_parsers)", "href": "(set by link_parsers)" }
      ],
      "author": {
        "name": "User Name",
        "email": "user.email@example.com",
        "timestamp": 1660330071
      },
      "committer": {
        "name": "User Name",
        "email": "user.email@example.com",
        "timestamp": 1660330071
      },
      "statistics": {
        "files_changed": 1,
        "additions": 1,
        "deletions": 0
      },
      "raw_message": "(full commit message including description, footers, etc.)"
    }
  ],
  "commit_id": "a440c6eb26404be4877b7e3ad592bfaa5d4eb210 (release commit)",
  "timestamp": 1625169301,
  "repository": "/path/to/repository",
  "commit_range": {
      "from": "(id of the first commit used for this release)",
      "to": "(id of the last commit used for this release)",
  },
  "statistics": {
    "commit_count": 1,
    "commits_timespan": 0,
    "conventional_commit_count": 0,
    "links": [
      {
        "text": "#452",
        "href": "https://github.com/orhun/git-cliff/issues/452",
        "count": 1
      }
    ],
    "days_passed_since_last_release": 0
  },
  "bump_type": "minor",
  "previous": {
    "version": "previous release"
  }
}

```

--------------------------------

### GitLab Commit Context in Templating

Source: https://git-cliff.org/docs/integration/gitlab

Example of how to access GitLab-specific commit details, such as username, pull request number, and labels, within changelog templates. This enables richer commit entries.

```json
{
  "id": "8edec7fd50f703811d55f14a3c5f0fd02b43d9e7",
  "message": "refactor(config): remove unnecessary newline from configs\n",
  "group": "🚜 Refactor",
  "...": "<strip>",
  "remote": {
    "username": "orhun",
    "pr_title": "some things have changed",
    "pr_number": 420,
    "pr_labels": ["rust"],
    "is_first_time": false
  }
}

```

```html
{% 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 -%}

```

--------------------------------

### Build Custom Docker Image

Source: https://git-cliff.org/docs/docker

Build a custom Docker image for git-cliff using the provided Dockerfile. Ensure DOCKER_BUILDKIT is enabled for enhanced build features.

```bash
DOCKER_BUILDKIT=1 docker build -t git-cliff .  
```

--------------------------------

### Generate Manpage

Source: https://git-cliff.org/docs/installation/build-from-source

Generate a manpage for git-cliff and place it in the target directory. This requires the built binary.

```bash
OUT_DIR=target target/release/git-cliff-mangen
```

--------------------------------

### Add and Update Nix Unstable Channel

Source: https://git-cliff.org/docs/installation/nix

These commands add the Nix unstable channel and update your package list to access the latest features and updates sooner. After updating, you can use the previous installation commands.

```bash
nix-channel --add https://nixos.org/channels/nixpkgs-unstable  
nix-channel --update nixpkgs  
```

--------------------------------

### GitLab Contributors Context in Templating

Source: https://git-cliff.org/docs/integration/gitlab

Example of the contributor data structure provided to the template context, including username, pull request details, and a flag indicating if it's their first contribution. This is used for generating contributor lists.

```json
{
  "version": "v1.4.0",
  "commits": [],
  "commit_id": "0af9eb24888d1a8c9b2887fbe5427985582a0f26",
  "timestamp": 0,
  "previous": null,
  "gitlab": {
    "contributors": [
      {
        "username": "orhun",
        "pr_title": "some things have changed",
        "pr_number": 420,
        "pr_labels": ["rust"],
        "is_first_time": true
      },
      {
        "username": "cliffjumper",
        "pr_title": "I love jumping",
        "pr_number": 999,
        "pr_labels": ["rust"],
        "is_first_time": true
      }
    ]
  }
}

```

```html
{% for contributor in gitlab.contributors | filter(attribute="is_first_time", value=true) %}
  * @{{ contributor.username }} made their first contribution in #{{ contributor.pr_number }}
{%- endfor -%}

```

--------------------------------

### Run git-cliff binary

Source: https://git-cliff.org/docs/installation/binary-releases

Execute the git-cliff binary directly from the extracted folder.

```bash
./git-cliff  
```

--------------------------------

### Navigate to extracted directory

Source: https://git-cliff.org/docs/installation/binary-releases

Change into the directory created after extracting the tarball.

```bash
cd "git-cliff-${version}"  
```

--------------------------------

### Configure Gitea Remote in Configuration File

Source: https://git-cliff.org/docs/integration/gitea

Set the owner, repository, and token for Gitea integration within the configuration file. Ensure the 'gitea' feature flag is enabled if building from source.

```toml
[remote.gitea]
owner = "orhun"
repo = "git-cliff"
token = "***"

```

--------------------------------

### Authenticate with Bitbucket using Environment Variable

Source: https://git-cliff.org/docs/integration/bitbucket

Use the BITBUCKET_TOKEN environment variable for authentication when running git-cliff with the --bitbucket-repo argument.

```bash
BITBUCKET_TOKEN="***" git cliff --bitbucket-repo "orhun/git-cliff"

```

--------------------------------

### Configure GitHub Remote

Source: https://git-cliff.org/docs/configuration/remote

Set the owner, repository, and token for GitHub integration. Ensure the token is kept secure.

```toml
[remote.github]
owner = "orhun"
repo = "git-cliff"
token = ""
```

--------------------------------

### Basic Git Configuration

Source: https://git-cliff.org/docs/configuration/git

This is the main git configuration block. It sets up commit parsing, filtering, and link generation rules.

```toml
[git]
conventional_commits = true
filter_unconventional = true
require_conventional = false
split_commits = false
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"},
]
protect_breaking_commits = false
filter_commits = false
fail_on_unmatched_commit = false
tag_pattern = "v[0-9].*"

skip_tags = "v0.1.0-beta.1"
ignore_tags = ""
topo_order = false
topo_order_commits = true
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"},
]
processing_order = [
    "commit_preprocessors",
    "split_commits",
    "conventional_commits",
    "commit_parsers",
    "link_parsers",
]
limit_commits = 42
recurse_submodules = false
include_paths = ["src/", "doc/**/*.md"]
exclude_paths = ["unrelated/"]

```

--------------------------------

### TOML Configuration File Path

Source: https://git-cliff.org/docs/configuration

git-cliff searches for configuration files in the project directory and then in the global user directory. It checks for specific filenames in a defined order.

```bash
cliff.toml
.cliff.toml
.config/cliff.toml
$HOME/cliff.toml
$HOME/.cliff.toml
$HOME/.config/cliff.toml
```

--------------------------------

### Run git-cliff from Docker Hub

Source: https://git-cliff.org/docs/docker

Use this command to run the latest git-cliff image from Docker Hub. Mounts the current directory to /app/ within the container.

```bash
docker run -t -v "$(pwd)":/app/ "orhunp/git-cliff:${TAG:-latest}"  
```

--------------------------------

### Minimal Changelog Output

Source: https://git-cliff.org/docs/templating/examples

This snippet shows a minimal changelog format, useful for basic version tracking.

```markdown
## 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

```

--------------------------------

### Basic Bump Configuration

Source: https://git-cliff.org/docs/configuration/bump

Sets default behavior for automatic minor and major version bumps, and defines the initial tag.

```toml
[bump]
features_always_bump_minor = true
breaking_always_bump_major = true
initial_tag = "0.1.0"

```

--------------------------------

### Generate Changelog with git-cliff-action

Source: https://git-cliff.org/docs/github-actions/git-cliff-action

This workflow snippet demonstrates how to use the git-cliff-action to generate a changelog. It checks out the repository, then uses the action to create a changelog based on a configuration file and arguments, outputting it to CHANGELOG.md.

```yaml
- name: Check out repository  
  uses: actions/checkout@v3  
  with:  
    fetch-depth: 0  
  
- name: Generate a changelog  
  uses: orhun/git-cliff-action@v4  
  with:  
    config: cliff.toml  
    args: --verbose  
  env:  
    OUTPUT: CHANGELOG.md  
    GITHUB_REPO: ${{ github.repository }}  

```

--------------------------------

### Skip Multiple Commits using .cliffignore

Source: https://git-cliff.org/docs/usage/skipping-commits

Create a `.cliffignore` file in your repository's root directory and list the SHA1 hashes of commits you wish to skip, each on a new line.

```bash
# contents of .cliffignore  
  
4f88dda8c746173ea59f920b7579b7f6c74bd6c8  
10c3194381f2cc4f93eb97404369568882ed8677  

```

--------------------------------

### Build git-cliff in Release Mode

Source: https://git-cliff.org/docs/installation/build-from-source

Compile the git-cliff project in release mode using Cargo. The output binary will be placed in the target/release directory.

```bash
CARGO_TARGET_DIR=target cargo build --release
```

--------------------------------

### Generate Shell Completions

Source: https://git-cliff.org/docs/installation/build-from-source

Generate shell completion scripts for git-cliff and place them in the target directory. This requires the built binary.

```bash
OUT_DIR=target target/release/git-cliff-completions
```

--------------------------------

### Use git-cliff Programmatic API

Source: https://git-cliff.org/docs/installation/npm

Integrate git-cliff into your own tooling by using its fully typed programmatic API in Node.js.

```typescript
import { runGitCliff, type Options } from "git-cliff";  
  
const options: Options = {  
  // ...  
};  
  
runGitCliff(options);  

```

--------------------------------

### Generate Flame Graph SVG

Source: https://git-cliff.org/docs/development/profiling

Runs the git-cliff project with the 'profiler' feature and 'bench' build profile enabled to generate performance profiling data, typically outputting a flame graph SVG for analysis.

```bash
cargo run --profile=bench --features=profiler  

```

--------------------------------

### Generate Changelog for Multiple Repositories

Source: https://git-cliff.org/docs/usage/multiple-repos

Specify multiple repository paths to generate a changelog that merges the history of these repositories. The `{{ repository }}` template variable can be used to identify the origin of each release.

```bash
git cliff --repository path1 path2  

```

--------------------------------

### Save Changelog Context to File

Source: https://git-cliff.org/docs/usage/print-context

Redirect the JSON changelog context to a file using the `--output` flag in addition to `--context`. This allows you to store the generated JSON for later use or analysis.

```bash
# save context to a file  
git cliff --context --output context.json  
```

--------------------------------

### Print Changelog Context to Stdout

Source: https://git-cliff.org/docs/usage/print-context

Use the `--context` flag to print the changelog context directly to standard output. This is useful for piping the JSON output to other tools or for quick inspection.

```bash
# print context to stdout  
git cliff --context  
```

--------------------------------

### Basic Changelog Output

Source: https://git-cliff.org/docs/templating/examples

The default changelog output generated by git-cliff based on the sample Git history.

```markdown
# 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 -->  

```

--------------------------------

### Generate GitHub Changelog

Source: https://git-cliff.org/docs/integration/github

Run this command to generate a changelog using the embedded `github.toml` configuration. This is useful for creating changelogs that match GitHub's default style.

```bash
git cliff -c github  

```

--------------------------------

### Save Changelog to Specified File

Source: https://git-cliff.org/docs/usage/examples

Specifies the output file path for the generated changelog. If no path is provided, it defaults to `CHANGELOG.md` in the current directory.

```bash
# Set output path
git cliff --output CHANGELOG.md

# Without path, the default is `CHANGELOG.md`
git cliff -o
```