git-cliff

Generates changelog files from the Git history by utilizing conventional commits as well as regex-powered custom parsers.

Runs as git-cliff|macOS, Linux, Windows|git-cliff.org

Open form in Otty otty.toml

Sync rules

What travels, what stays, what never leaves

git-cliff in your home directory Every rule on this page, by file

remote.*.token

Lifted into your secret store; the rest of the file syncs.

remote.*.token

Lifted into your secret store; the rest of the file syncs.

Only what the catalog names. A directory that syncs brings everything inside it except what is listed as excluded here.

apps/git-cliff/otty.tomlThe file this page is generated from

id = "git-cliff"

name = "git-cliff"

homepage = "https://git-cliff.org"

description = "Generates changelog files from the Git history by utilizing conventional commits as well as regex-powered custom parsers."

# The apple-touch-icon from the project's homepage.

icon = "https://git-cliff.org/favicon/apple-touch-icon.png"

executables = ["git-cliff"]

[dotfiles]

# https://git-cliff.org/docs/configuration — the global configuration file is

# <CONFIG_DIR>/git-cliff/cliff.toml, where CONFIG_DIR is $XDG_CONFIG_HOME (or

# ~/.config) on Linux and macOS and %APPDATA% on Windows: the [configHome] base

# directory. The second entry is the legacy macOS location the same page still

# supports, and macOS is the only platform that has it, so it stays literal.

# The cliff.toml / .cliff.toml / .config/cliff.toml the same page lists first

# are the ones inside a repository — that project's config, not a dotfile.

paths = [

"[configHome]/git-cliff/cliff.toml",

"~/Library/Application Support/git-cliff/cliff.toml",

]

exclude = []

# The file is changelog templates and commit parsers; only the remote access

# tokens inside it are credentials, and those are lifted out below.

secret = []

# Read once per run; git-cliff is not resident.

side_effect = false

# https://git-cliff.org/docs/configuration/remote — every [remote.<provider>]

# table takes a `token` that "sets the access token for the remote", the same

# value --github-token / GITHUB_TOKEN carries. Named under both spellings, or a

# token in the legacy macOS file syncs in the clear.

[[dotfiles.secret_paths]]

file = [

"[configHome]/git-cliff/cliff.toml",

"~/Library/Application Support/git-cliff/cliff.toml",

]

match = { key_path = ["remote.*.token"] }

# No machine_lines: the rest of cliff.toml is templates, commit parsers and

# link definitions — exactly the settings a user wants identical everywhere.

[commands]

format = 1

label = "Generate changelog"

description = "Generate a changelog from git history with git-cliff. Commit-parser, template and remote-integration options are left out."

quality = "ai-draft"

base = "fig:git-cliff"

parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = false }

[[commands.source]]

id = "fig"

kind = "completion"

url = "https://github.com/withfig/autocomplete/blob/master/src/git-cliff.ts"

license = "MIT"

[[commands.field]]

id = "range"

label = "Commit range"

description = "A git revision range such as v1.0.0..HEAD. Leave empty to process the whole history."

type = "string"

position = 0

sources = ["fig"]

[[commands.field]]

id = "unreleased"

label = "Unreleased only"

description = "Process only commits that do not belong to a tag."

type = "boolean"

option = ["--unreleased", "-u"]

sources = ["fig"]

[[commands.field]]

id = "latest"

label = "Latest tag only"

description = "Process commits starting from the latest tag."

type = "boolean"

option = ["--latest", "-l"]

sources = ["fig"]

[[commands.field]]

id = "current"

label = "Current tag only"

description = "Process the commits that belong to the current tag."

type = "boolean"

option = ["--current"]

sources = ["fig"]

[[commands.field]]

id = "tag"

label = "Tag for unreleased"

description = "Version label to use for the unreleased commits."

type = "string"

option = ["--tag", "-t"]

sources = ["fig"]

[[commands.field]]

id = "output"

label = "Output file"

description = "Write the changelog to this file instead of the terminal."

type = "path"

option = ["--output", "-o"]

path = { kind = "file", role = "output" }

effect = "overwrite"

sources = ["fig"]

[[commands.field]]

id = "prepend"

label = "Prepend to file"

description = "Prepend the new entries to an existing changelog file."

type = "path"

option = ["--prepend", "-p"]

path = { kind = "file", role = "output" }

effect = "overwrite"

sources = ["fig"]

[[commands.field]]

id = "config"

label = "Config file"

description = "Defaults to cliff.toml."

type = "path"

option = ["--config", "-c"]

path = { kind = "file", role = "input" }

sources = ["fig"]

[[commands.field]]

id = "repository"

label = "Repository"

description = "Git repository to read."

type = "path"

option = ["--repository", "-r"]

path = { kind = "directory", role = "input" }

sources = ["fig"]

[[commands.field]]

id = "strip"

label = "Strip part"

type = "string"

option = ["--strip", "-s"]

suggestions = [{ value = "header", label = "Header" }, { value = "footer", label = "Footer" }, { value = "all", label = "Both" }]

sources = ["fig"]

[[commands.field]]

id = "sort"

label = "Commit sorting"

type = "string"

option = ["--sort"]

suggestions = [{ value = "oldest", label = "Oldest first" }, { value = "newest", label = "Newest first" }]

sources = ["fig"]

[[commands.field]]

id = "init"

label = "Write default cliff.toml"

description = "Create a default configuration file instead of a changelog."

type = "boolean"

option = ["--init", "-i"]

effect = "overwrite"

sources = ["fig"]

[[commands.field]]

id = "verbose"

label = "Verbosity"

type = "count"

option = ["--verbose", "-v"]

description = "Repeat for more detail."

sources = ["fig"]

[[commands.task]]

id = "unreleased"

label = "Unreleased changes"

fields = ["unreleased", "tag", "output", "prepend", "config"]

required = []

set = { unreleased = [true] }

[[commands.task]]

id = "latest"

label = "Latest release"

fields = ["latest", "output", "config"]

required = []

set = { latest = [true] }

[[commands.task]]

id = "full"

label = "Full changelog"

fields = ["range", "output", "config", "sort"]

required = []

[[commands.group]]

id = "basic"

label = "Basic"

fields = ["range", "unreleased", "latest", "tag", "output"]

[[commands.group]]

id = "advanced"

label = "Advanced"

fields = ["current", "strip", "sort", "init", "config", "repository", "verbose", "prepend"]

Use it with your dotfile manager

Same data, in the shape your tool already reads

Opens Otty and adds this tool to what it syncs

Opens otty://sync/add/git-cliff. Otty ships with this catalog, so the link only has to name the tool — nothing is downloaded.

Every one of these is generated from the same rules as this page.