Skip to main content

​
Quickstart Guide

Get started with git-cliff and generate your first changelog in just a few steps.
1

Install git-cliff

The quickest way to install git-cliff is using Cargo:
cargo install git-cliff
See the Installation page for alternative installation methods including package managers, Docker, and pre-built binaries.
Verify the installation:
git-cliff --version
2

Initialize Configuration

Navigate to your Git repository and initialize git-cliff:
cd your-project
git-cliff --init
This creates a cliff.toml configuration file in your repository with sensible defaults.
You can also specify a custom template name: git-cliff --init github or provide a path to your own config file.

​
Understanding the Configuration

The generated cliff.toml includes three main sections:
[changelog]
# Template for the changelog header
header = """# Changelog\n"""
# Template for each release
body = """
{% for group, commits in commits | group_by(attribute="group") %}
    ### {{ group | upper_first }}
    {% for commit in commits %}
        - {{ commit.message }}
    {% endfor %}
{% endfor %}
"""
# Template for the footer
footer = """<!-- generated by git-cliff -->"""
You can edit this file to customize your changelog format. Check out the templating examples for different templates like Keep a Changelog, minimal, detailed, and more.
3

Generate Your First Changelog

Generate a changelog for your entire Git history:
git-cliff -o CHANGELOG.md
This command:
  • Analyzes your Git commit history
  • Groups commits by type (features, fixes, etc.)
  • Generates a formatted changelog
  • Writes the output to CHANGELOG.md
This will overwrite any existing CHANGELOG.md file. Use --prepend if you want to preserve existing content.

​
Common Options

# Generate changelog for only the latest release
git-cliff --latest -o CHANGELOG.md
4

View Your Changelog

Open the generated CHANGELOG.md to see your formatted changelog:
Example Output
# Changelog

## [2.12.0] - 2026-01-20

### ⛰️  Features

- *(args)* Add offline flag (#1321) - (f19f1cd)
- *(args)* Add `--skip-tags` cli argument (#1334) - (32cf8c5)
- *(logging)* Implement commit processing summary (#1355) - (aa01a09)

### 🐛 Bug Fixes

- *(config)* Respect the changelog.output configuration (#1349) - (cfcc5ae)
- *(remote)* Avoid false first-time contributors (#1348) - (de7cf02)

### 📚 Documentation

- *(contributing)* Clarify Rust toolchain requirements (#1344) - (97b0322)
- *(install)* Add mise alternative method installation (#1320) - (34b8d30)

## New Contributors ❤️

* @taladar made their first contribution in #1319
* @barskern made their first contribution in #1321
Your changelog includes:
  • ✅ Grouped commits by type
  • ✅ Commit links and hashes
  • ✅ Issue/PR references
  • ✅ Scoped changes (when using conventional commits)
  • ✅ Version headers with dates

​
Next Steps

Configuration Guide

Deep dive into configuration options and customize your changelog format

Templating

Learn how to create custom templates with Tera

Command-Line Usage

Explore all CLI options and advanced usage examples

Integrations

Connect with GitHub, GitLab, and other Git hosting services

​
Tips for Better Changelogs

Follow Conventional Commits: Structure your commit messages using the conventional commits format for automatic categorization:
feat(parser): add support for custom delimiters
fix(cli): resolve path handling on Windows
docs(readme): update installation instructions
Key prefixes:
  • feat: - New features (minor version bump)
  • fix: - Bug fixes (patch version bump)
  • feat!: or fix!: - Breaking changes (major version bump)
  • docs: - Documentation updates
  • perf: - Performance improvements
  • refactor: - Code refactoring
When working with pull requests, use squash merges for a cleaner Git history. This makes each PR a single commit, which works better with git-cliff’s commit parsing.

​
Troubleshooting

​
No Output Generated

If git-cliff doesn’t generate any output:
  1. Check that you have commits in your repository
  2. Verify your commit_parsers configuration matches your commit format
  3. Try disabling filter_unconventional if you don’t use conventional commits:
[git]
conventional_commits = false
filter_unconventional = false

​
Commits Not Grouped Correctly

Ensure your commit messages match the patterns in your commit_parsers: 
# Check what git-cliff sees
git-cliff --verbose

​
Can’t Find Configuration File

By default, git-cliff looks for cliff.toml in the current directory. Specify a custom location: 
git-cliff --config path/to/cliff.toml -o CHANGELOG.md

​
Getting Help

Need assistance? Here are some resources:

Build docs developers (and LLMs) love

Get started for freeTalk to us