Skip to main content
git-cliff provides a powerful command-line interface for generating changelogs from your Git history. This section covers the most common workflows and use cases.

​
Quick Start

Generate a changelog for your entire repository: 
git cliff
This command reads your configuration from cliff.toml and generates a changelog based on your commit history.

​
Common Workflows

​
Generating Changelogs for Releases

When preparing a new release, you can generate a changelog for unreleased changes: 
# Generate changelog for unreleased commits
git cliff --unreleased

# Generate changelog and tag the release
git cliff --unreleased --tag v1.0.0

​
Updating Existing Changelogs

Prepend new changes to your existing CHANGELOG.md: 
git cliff --unreleased --tag v1.0.0 --prepend CHANGELOG.md

​
Version Bumping

Automatically calculate the next semantic version: 
# Automatically determine version bump
git cliff --bump

# Get just the version number
git cliff --bumped-version

​
Filtering Commits

Generate changelogs for specific parts of your history: 
# Only the latest tag
git cliff --latest

# Specific commit range
git cliff v1.0.0..v2.0.0

# All unreleased changes
git cliff --unreleased

​
Output Options

​
Save to File

# Save to CHANGELOG.md (default)
git cliff -o

# Save to custom file
git cliff --output HISTORY.md

​
Different Formats

# JSON context for processing
git cliff --context

# Custom template
git cliff --body "{% for commit in commits %}{{ commit.message }}\n{% endfor %}"

​
Explore More

Basic Usage

Learn core commands and common patterns

CLI Arguments

Complete reference of all command-line options

Version Bumping

Automatically calculate semantic versions

Monorepos

Generate changelogs for specific paths

Submodules

Include submodule commits in changelogs

​
Next Steps

Once you’re familiar with the basics, explore:

Build docs developers (and LLMs) love

Get started for freeTalk to us