git-cliff(1)

📦
version 2.14.2 · 5 versions
, in arch rolling

✨ git-cliff(1) ✨

okay so bestie, welcome to the git-cliff manual page 💖 this is the General Commands Manual entry, and honestly? it's giving main character energy for your changelogs. buckle up 🎀

🌸 NAME 🌸

git-cliff — a highly customizable changelog generator ⛰️

🦋 SYNOPSIS 🦋

git-cliff [-h|--help] [-V|--version] [-v|--verbose]... [-i|--init]
[--templates-dir] [--list-templates] [-c|--config] [--config-url]
[-w|--workdir] [-r|--repository] [--include-path] [--exclude-path]
[--tag-pattern] [--with-commit] [--with-tag-message] [--skip-tags]
[--ignore-tags] [--count-tags] [--limit-tags] [--skip-commit]
[-p|--prepend] [-o|--output] [-t|--tag] [--bump] [--bumped-version]
[-b|--body] [--body-file] [-l|--latest] [--current] [-u|--unreleased]
[--topo-order] [--use-branch-tags] [--no-exec] [-x|--context]
[--from-context] [-s|--strip] [--sort] [--github-token] [--github-repo]
[--gitlab-token] [--gitlab-repo] [--gitea-token] [--gitea-repo]
[--bitbucket-token] [--bitbucket-repo] [--http-timeout]
[--use-native-tls] [--offline] [RANGE]

like, that's a lot of brackets, i know 😭 but every single one of them is doing something, i promise.

💅 DESCRIPTION 💅

A highly customizable changelog generator ⛰️ — that's the whole pitch, no cap. it takes your git history and turns it into a changelog that actually slaps 🔥

⭐ FLAGS ⭐

  • -h, --help — prints help information 🫶
  • -V, --version — prints version information
  • -v, --verbose — increases the logging verbosity (yes bestie, it's stackable — you can pass it more than once for extra chatter) 🙈
  • --list-templates — prints the names of the available templates (built-in and user-defined) 👑
  • --bumped-version — prints bumped version for unreleased changes
  • -l, --latest — processes the commits starting from the latest tag
  • --current — processes the commits that belong to the current tag
  • -u, --unreleased — processes the commits that do not belong to a tag
  • --topo-order — sorts the tags topologically
  • --use-branch-tags — include only the tags that belong to the current branch 🌿
  • --no-exec — disables the external command execution 🚫
  • -x, --context — prints changelog context as JSON
  • --use-native-tls — load TLS certificates from the native certificate store 🔐

🎀 OPTIONS 🎀

  • -i, --init [<CONFIG>] — writes the default configuration file to cliff.toml ✨
  • --templates-dir <PATH> — sets the directory to look up user-defined templates for --init. a user-defined template overrides a built-in template of the same name. may also be specified with the GIT_CLIFF_TEMPLATES_DIR environment variable.
  • -c, --config <PATH> — sets the configuration file. when omitted, the configuration is discovered automatically (a project cliff.toml / .cliff.toml / .config/cliff.toml, then the user configuration directory), falling back to the built-in default. may also be specified with the GIT_CLIFF_CONFIG environment variable. 🧚
  • --config-url <URL> — sets the URL for the configuration file. may also be specified with the GIT_CLIFF_CONFIG_URL environment variable.
  • -w, --workdir <PATH> — sets the working directory. may also be specified with the GIT_CLIFF_WORKDIR environment variable.
  • -r, --repository <PATH>... — sets the git repository (yep, the ... means you can stack it 💀). may also be specified with the GIT_CLIFF_REPOSITORY environment variable.
  • --include-path <PATTERN> — sets the path to include related commits. may also be specified with the GIT_CLIFF_INCLUDE_PATH environment variable.
  • --exclude-path <PATTERN> — sets the path to exclude related commits. may also be specified with the GIT_CLIFF_EXCLUDE_PATH environment variable.
  • --tag-pattern <PATTERN> — sets the regex for matching git tags. may also be specified with the GIT_CLIFF_TAG_PATTERN environment variable.
  • --with-commit <MSG> — sets custom commit messages to include in the changelog. may also be specified with the GIT_CLIFF_WITH_COMMIT environment variable.
  • --with-tag-message [<MSG>] — sets custom message for the latest release. may also be specified with the GIT_CLIFF_WITH_TAG_MESSAGE environment variable.
  • --skip-tags <PATTERN> — sets the tags to skip in the changelog. may also be specified with the GIT_CLIFF_SKIP_TAGS environment variable.
  • --ignore-tags <PATTERN> — sets the tags to ignore in the changelog. may also be specified with the GIT_CLIFF_IGNORE_TAGS environment variable.
  • --count-tags <PATTERN> — sets the tags to count in the changelog. may also be specified with the GIT_CLIFF_COUNT_TAGS environment variable.
  • --limit-tags <N> — limits the number of tags to process. may also be specified with the GIT_CLIFF_LIMIT_TAGS environment variable.
  • --skip-commit <SHA1> — sets commits that will be skipped in the changelog. may also be specified with the GIT_CLIFF_SKIP_COMMIT environment variable.
  • -p, --prepend [<PATH>] — prepends entries to the given changelog file. may also be specified with the GIT_CLIFF_PREPEND environment variable.
  • -o, --output [<PATH>] — writes output to the given file. may also be specified with the GIT_CLIFF_OUTPUT environment variable.
  • -t, --tag <TAG> — sets the tag for the latest version. may also be specified with the GIT_CLIFF_TAG environment variable.
  • --bump [<BUMP>] — bumps the version for unreleased changes. optionally with specified version 🔥
  • -b, --body <TEMPLATE> — sets the template for the changelog body. may also be specified with the GIT_CLIFF_TEMPLATE environment variable.
  • --body-file <PATH> — reads the template for the changelog body from a file 📄
  • --from-context <PATH> — generates changelog from a JSON context. may also be specified with the GIT_CLIFF_CONTEXT environment variable.
  • -s, --strip <PART> — strips the given parts from the changelog. possible values are:
    • header
    • footer
    • all
  • --sort <SORT> — sets sorting of the commits inside sections. default: oldest. possible values are:
    • oldest
    • newest

🌈 REMOTE OPTIONS 🌈

  • --github-token <TOKEN> — sets the GitHub API token. may also be specified with the GITHUB_TOKEN environment variable.
  • --github-repo <OWNER/REPO> — sets the GitHub repository. may also be specified with the GITHUB_REPO environment variable.
  • --gitlab-token <TOKEN> — sets the GitLab API token. may also be specified with the GITLAB_TOKEN environment variable.
  • --gitlab-repo <OWNER/REPO> — sets the GitLab repository. may also be specified with the GITLAB_REPO environment variable.
  • --gitea-token <TOKEN> — sets the Gitea API token. may also be specified with the GITEA_TOKEN environment variable.
  • --gitea-repo <OWNER/REPO> — sets the Gitea repository. may also be specified with the GITEA_REPO environment variable.
  • --bitbucket-token <TOKEN> — sets the Bitbucket API token. may also be specified with the BITBUCKET_TOKEN environment variable.
  • --bitbucket-repo <OWNER/REPO> — sets the Bitbucket repository. may also be specified with the BITBUCKET_REPO environment variable.
  • --http-timeout <SECS> — sets the HTTP timeout for remote metadata requests in seconds ⏱️ may also be specified with the GIT_CLIFF_HTTP_TIMEOUT environment variable.
  • --offline — disable network access for remote repositories. may also be specified with the GIT_CLIFF_OFFLINE environment variable.
bestie this whole section is about remote metadata, so if you're offline (like, literally on a plane 🛫) the --offline flag is your bestie too.

🍓 ARGS 🍓

  • [RANGE] — sets the commit range to process

💜 VERSION 💜

v2.14.2

👑 AUTHORS 👑

git-cliff contributors <git-cliff@protonmail.com>

and that's the whole page, periodt 💅 this was git-cliff 2.14.2 — that's the source/version and date wrapped up in a cute little bow for you, bestie 🎀🫶 now go generate some iconic changelogs ✨

📦 where this page comes from