Command-Line Arguments

Complete command-line reference for git-cliff. All options can also be set via environment variables or configuration files.

Usage

git-cliff [FLAGS] [OPTIONS] [--] [RANGE]

Flags

Flags are boolean options that don’t take values.

-h, --help

flag

Prints help information

git cliff --help

-V, --version

flag

Prints version information

git cliff --version
# Output: git-cliff 2.0.0

-v, --verbose

flag

Increases the logging verbosity. Can be used multiple times for more verbose output.

# Basic verbosity
git cliff -v

# More verbose
git cliff -vv

# Maximum verbosity
git cliff -vvv

-l, --latest

flag

Processes the commits starting from the latest tag

git cliff --latest

Useful for generating changelog entries for only the most recent release.

--current

flag

Processes the commits that belong to the current tag

git checkout v1.0.0
git cliff --current

Requires HEAD to be on a tagged commit.

-u, --unreleased

flag

Processes the commits that do not belong to a tag

git cliff --unreleased
git cliff --unreleased --tag v2.0.0

Often combined with --tag to preview the next release.

--topo-order

flag

Sorts the tags topologically instead of chronologically

git cliff --topo-order

Useful for repositories with complex branching strategies.

--use-branch-tags

flag

Include only the tags that belong to the current branch

git cliff --use-branch-tags

Helpful when working with multiple release branches.

--no-exec

flag

Disables the external command execution

git cliff --no-exec

Skips running preprocessors and postprocessors defined in configuration.

-x, --context

flag

Prints changelog context as JSON

git cliff --context > changelog.json

Useful for processing changelog data with external tools.

--bumped-version

flag

Prints bumped version for unreleased changes

VERSION=$(git cliff --bumped-version)
echo "Next version: $VERSION"

Calculates the next semantic version based on conventional commits.

--use-native-tls

flag

Load TLS certificates from the native certificate store

git cliff --config-url https://example.com/cliff.toml --use-native-tls

Only available when compiled with the remote feature.

Configuration Options

-i, --init

string

default:"cliff.toml"

Writes the default configuration file to cliff.toml. Optionally accepts a template name.

# Create default config
git cliff --init

# Create with template
git cliff --init keepachangelog

# Custom filename
git cliff --init --config custom.toml

Available templates: keepachangelog, github, detailed, minimal, scoped, scopesorted, cocogitto, unconventional

-c, --config

path

default:"cliff.toml"

Sets the configuration file pathEnvironment variable: GIT_CLIFF_CONFIG

git cliff --config custom.toml
git cliff -c configs/release.toml

# Using environment variable
export GIT_CLIFF_CONFIG=custom.toml
git cliff

--config-url

url

Sets the URL for the configuration fileEnvironment variable: GIT_CLIFF_CONFIG_URL

git cliff --config-url https://example.com/cliff.toml

Only available when compiled with the remote feature.

Repository Options

-w, --workdir

path

Sets the working directoryEnvironment variable: GIT_CLIFF_WORKDIR

git cliff --workdir /path/to/repo

-r, --repository

path[]

Sets the git repository path(s). Accepts multiple paths.Environment variable: GIT_CLIFF_REPOSITORY

# Single repository
git cliff --repository /path/to/repo

# Multiple repositories (merged history)
git cliff --repository /path/to/repo1 /path/to/repo2

Filtering Options

--include-path

pattern[]

Sets the path pattern to include related commits. Accepts glob patterns.Environment variable: GIT_CLIFF_INCLUDE_PATH

# Include specific directory
git cliff --include-path "src/api/**/*"

# Multiple patterns
git cliff --include-path "src/**/*" --include-path "lib/**/*"

Paths must be relative to the repository root.

--exclude-path

pattern[]

Sets the path pattern to exclude related commits. Accepts glob patterns.Environment variable: GIT_CLIFF_EXCLUDE_PATH

# Exclude specific directory
git cliff --exclude-path "docs/**/*"

# Exclude multiple patterns
git cliff --exclude-path "*.md" --exclude-path "tests/**/*"

--tag-pattern

regex

Sets the regex pattern for matching git tagsEnvironment variable: GIT_CLIFF_TAG_PATTERN

# Only match version tags
git cliff --tag-pattern "v[0-9]+\.[0-9]+\.[0-9]+"

# Match tags with prefix
git cliff --tag-pattern "release/.*"

--skip-tags

regex

Sets the regex pattern for tags to skip in the changelogEnvironment variable: GIT_CLIFF_SKIP_TAGS

# Skip beta releases
git cliff --skip-tags ".*beta.*"

Skipped tags are processed but not included in the output.

--ignore-tags

regex

Sets the regex pattern for tags to ignore in the changelogEnvironment variable: GIT_CLIFF_IGNORE_TAGS

# Ignore RC tags
git cliff --ignore-tags ".*rc[0-9]+"

Ignored tags are completely skipped during processing.

--count-tags

regex

Sets the regex pattern for tags to count in the changelogEnvironment variable: GIT_CLIFF_COUNT_TAGS

# Only count stable releases
git cliff --count-tags "v[0-9]+\.[0-9]+\.[0-9]+$"

--skip-commit

sha1[]

Sets commits that will be skipped in the changelog. Accepts multiple commit SHAs.Environment variable: GIT_CLIFF_SKIP_COMMIT

git cliff --skip-commit abc123 --skip-commit def456

Output Options

-o, --output

path

default:"CHANGELOG.md"

Writes output to the given file. If no path is provided, defaults to CHANGELOG.md.Environment variable: GIT_CLIFF_OUTPUT

# Use default filename
git cliff -o

# Custom filename
git cliff --output HISTORY.md

# Custom path
git cliff --output docs/CHANGELOG.md

-p, --prepend

path

Prepends entries to the given changelog fileEnvironment variable: GIT_CLIFF_PREPEND

git cliff --unreleased --tag v1.0.0 --prepend CHANGELOG.md

The --prepend option is incompatible with -o if the file paths are equal.

-s, --strip

enum

Strips the given parts from the changelogValues: header, footer, all

# Remove header
git cliff --strip header

# Remove footer
git cliff --strip footer

# Remove both
git cliff --strip all

Template Options

-b, --body

template

Sets the template for the changelog bodyEnvironment variable: GIT_CLIFF_TEMPLATE

# Simple list of commits
git cliff --body "{% for commit in commits %}{{ commit.message }}\n{% endfor %}"

# With custom formatting
git cliff --body "## Changes\n{% for commit in commits %}- {{ commit.message }}\n{% endfor %}"

--from-context

path

Generates changelog from a JSON context fileEnvironment variable: GIT_CLIFF_CONTEXT

# Export context
git cliff --context > context.json

# Generate from context
git cliff --from-context context.json

Version and Tag Options

-t, --tag

string

Sets the tag for the latest versionEnvironment variable: GIT_CLIFF_TAG

# Set tag for unreleased changes
git cliff --unreleased --tag v2.0.0

# Tag with prefix
git cliff --tag testing/v1.0.0-beta.1

Note: This does not create an actual Git tag.

--bump

enum

default:"auto"

Bumps the version for unreleased changes. Optionally with specified version type.Values: auto, major, minor, patch

# Automatic bump based on conventional commits
git cliff --bump

# Force major version bump
git cliff --bump major

# Force minor version bump
git cliff --bump minor

# Force patch version bump
git cliff --bump patch

See Version Bumping for more details.

Commit Options

--with-commit

string[]

Sets custom commit messages to include in the changelogEnvironment variable: GIT_CLIFF_WITH_COMMIT

# Add custom commit
git cliff --with-commit "feat: add new feature"

# Add commit with SHA
git cliff --with-commit "8f55e69 feat: add new feature"

# Multiple commits
git cliff --with-commit "feat: add X" --with-commit "fix: resolve Y"

--with-tag-message

string

Sets custom message for the latest releaseEnvironment variable: GIT_CLIFF_WITH_TAG_MESSAGE

git cliff --with-tag-message "This is a special release"

Sorting Options

--sort

enum

default:"oldest"

Sets sorting of the commits inside sectionsValues: oldest, newest

# Oldest commits first (default)
git cliff --sort oldest

# Newest commits first
git cliff --sort newest

Remote Integration Options

These options are only available when compiled with the respective feature flags.

GitHub

--github-token

token

Sets the GitHub API tokenEnvironment variable: GITHUB_TOKEN

git cliff --github-token ghp_xxxxxxxxxxxx

# Using environment variable
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
git cliff

--github-repo

owner/repo

Sets the GitHub repositoryEnvironment variable: GITHUB_REPO

git cliff --github-repo orhun/git-cliff

# With full URL
git cliff --github-repo https://github.com/orhun/git-cliff

GitLab

--gitlab-token

token

Sets the GitLab API tokenEnvironment variable: GITLAB_TOKEN

git cliff --gitlab-token glpat-xxxxxxxxxxxx

--gitlab-repo

owner/repo

Sets the GitLab repositoryEnvironment variable: GITLAB_REPO

git cliff --gitlab-repo group/project

# Nested groups
git cliff --gitlab-repo group/subgroup/project

Gitea

--gitea-token

token

Sets the Gitea API tokenEnvironment variable: GITEA_TOKEN

git cliff --gitea-token xxxxxxxxxxxx

--gitea-repo

owner/repo

Sets the Gitea repositoryEnvironment variable: GITEA_REPO

git cliff --gitea-repo owner/repo

Bitbucket

--bitbucket-token

token

Sets the Bitbucket API tokenEnvironment variable: BITBUCKET_TOKEN

git cliff --bitbucket-token xxxxxxxxxxxx

--bitbucket-repo

owner/repo

Sets the Bitbucket repositoryEnvironment variable: BITBUCKET_REPO

git cliff --bitbucket-repo owner/repo

Azure DevOps

--azure-devops-token

token

Sets the Azure DevOps API tokenEnvironment variable: AZURE_DEVOPS_TOKEN

git cliff --azure-devops-token xxxxxxxxxxxx

--azure-devops-repo

owner/repo

Sets the Azure DevOps repositoryEnvironment variable: AZURE_DEVOPS_REPO

git cliff --azure-devops-repo organization/project

General Remote Options

--offline

flag

Disable network access for remote repositories

git cliff --offline

Useful when working without internet connectivity or for faster execution.

Arguments

RANGE

string

Sets the commit range to process. Uses Git range syntax.

# Between two commits
git cliff abc123..def456

# From commit to HEAD
git cliff abc123..HEAD

# Between two tags
git cliff v1.0.0..v2.0.0

# From tag to HEAD
git cliff v1.0.0..

# Last N commits
git cliff HEAD~5..

See Git range syntax for more patterns.

Environment Variables

All options can be set via environment variables using the GIT_CLIFF_ prefix:

# Set config file
export GIT_CLIFF_CONFIG="custom.toml"

# Set output file
export GIT_CLIFF_OUTPUT="CHANGELOG.md"

# Set repository
export GIT_CLIFF_REPOSITORY="/path/to/repo"

# Set tag pattern
export GIT_CLIFF_TAG_PATTERN="v[0-9]+\.[0-9]+\.[0-9]+"

# Set GitHub token
export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"

# Run git-cliff
git cliff

Configuration Precedence

Configuration values are applied in the following order (later sources override earlier ones):

Default values
Configuration file (cliff.toml)
Environment variables
Command-line arguments

Examples

Generate Full Changelog

git cliff -o CHANGELOG.md

Release Workflow

# Calculate next version
VERSION=$(git cliff --bumped-version)

# Generate changelog
git cliff --tag "$VERSION" --unreleased -o CHANGELOG.md

# Create tag
git tag "$VERSION"

Monorepo Package Release

git cliff --include-path "packages/api/**/*" \
  --tag "api-v1.2.0" \
  --unreleased \
  -o packages/api/CHANGELOG.md

Export for External Processing

git cliff --context | jq '.[] | select(.version == "1.0.0")'

Get Started

Installation

Usage

Configuration

Templating

Command-Line Arguments

Usage

Flags

Configuration Options

Repository Options

Filtering Options

Output Options

Template Options

Version and Tag Options

Commit Options

Sorting Options

Remote Integration Options

GitHub

GitLab

Gitea

Bitbucket

Azure DevOps

General Remote Options

Arguments

Environment Variables

Configuration Precedence

Examples

Generate Full Changelog

Release Workflow

Monorepo Package Release

Export for External Processing

See Also

Build docs developers (and LLMs) love

Get Started

Installation

Usage

Configuration

Templating

​Usage

​Flags

​Configuration Options

​Repository Options

​Filtering Options

​Output Options

​Template Options

​Version and Tag Options

​Commit Options

​Sorting Options

​Remote Integration Options

​GitHub

​GitLab

​Gitea

​Bitbucket

​Azure DevOps

​General Remote Options

​Arguments

​Environment Variables

​Configuration Precedence

​Examples

​Generate Full Changelog

​Release Workflow

​Monorepo Package Release

​Export for External Processing

​See Also

Build docs developers (and LLMs) love

Usage

Flags

Configuration Options

Repository Options

Filtering Options

Output Options

Template Options

Version and Tag Options

Commit Options

Sorting Options

Remote Integration Options

GitHub

GitLab

Gitea

Bitbucket

Azure DevOps

General Remote Options

Arguments

Environment Variables

Configuration Precedence

Examples

Generate Full Changelog

Release Workflow

Monorepo Package Release

Export for External Processing

See Also