orhunp/git-cliff

git-cliff Docker镜像文档

概述

git-cliff是一个基于Git历史生成结构化变更日志的工具，严格遵循Conventional Commits规范，支持高度自定义的输出格式。该Docker镜像封装了git-cliff的核心功能，可快速集成到开发流程中，无需本地安装依赖，简化变更日志的生成与维护流程。

主要用途：从Git提交历史中提取符合规范的提交信息，自动生成、更新变更日志文档（如CHANGELOG.md），适用于各类软件项目的版本发布周期。

核心功能和特性

遵循行业标准

• 严格支持Conventional Commits规范，自动识别feat/fix/docs等提交类型
• 兼容Semantic Versioning版本号规则，辅助版本号管理

高度可定制化

• 通过TOML配置文件（cliff.toml）自定义变更日志结构、分类、排序规则
• 支持模板系统，可定义标题格式、提交信息展示方式、章节划分
• 内置多种预设模板（如angular/keepachangelog风格），也可完全自定义

多格式输出与集成

• 默认生成Markdown格式变更日志，支持输出为纯文本、JSON等格式
• 可集成到Git工作流、CI/CD管道（如GitHub Actions、GitLab CI）实现自动化生成
• 支持增量更新模式，仅追加新变更内容至现有变更日志

Git历史分析能力

• 智能解析Git标签、分支、提交作者信息
• 支持按版本范围（如v1.0.0..v1.1.0）、提交作者、提交类型筛选变更内容
• 自动识别重大变更（BREAKING CHANGE）并突出显示

使用场景和适用范围

适用场景

• 开源项目：为用户提供清晰的版本迭代记录，便于跟踪功能新增与问题修复
• 团队协作：统一变更日志格式，减少人工编写成本，提升团队协作效率
• CI/CD流程：在发布流程中自动生成变更日志，作为版本发布文档的一部分
• 版本管理：辅助维护版本历史，支持基于变更内容快速定位特定版本

适用范围

• 采用Git作为版本控制系统的软件项目
• 遵循或计划遵循Conventional Commits规范的开发团队
• 需要自动化维护变更日志的中小型项目及大型企业级应用

详细使用方法和配置说明

基本使用（Docker Run）

生成完整变更日志

在项目根目录执行以下命令，生成基于当前Git历史的变更日志：

bash
docker run --rm -v "$(pwd):/app" orhunp/git-cliff:latest generate

指定输出文件

将变更日志输出到自定义文件（默认输出至标准输出）：

bash
docker run --rm -v "$(pwd):/app" orhunp/git-cliff:latest generate --output CHANGELOG.md

使用自定义配置文件

通过--config参数指定自定义配置文件路径（默认读取项目根目录的cliff.toml）：

bash
docker run --rm -v "$(pwd):/app" orhunp/git-cliff:latest generate --config .config/cliff.toml

生成特定版本范围的变更日志

仅包含v1.0.0至v1.1.0版本间的变更：

bash
docker run --rm -v "$(pwd):/app" orhunp/git-cliff:latest generate --tag-range v1.0.0..v1.1.0

配置文件说明

git-cliff通过cliff.toml（默认路径）实现自定义配置，核心配置项包括：

基础配置示例（cliff.toml）

toml
[changelog]
# 变更日志标题
header = "# Changelog\n\nAll notable changes to this project will be documented in this file."
# 版本排序（asc/desc）
sort = "desc"
# 是否显示未发布版本
unreleased = true
# 未发布版本标题
unreleased_title = "## [Unreleased]"

[git]
# 包含的提交类型
commit_types = [
  { type = "feat", section = "Features" },
  { type = "fix", section = "Bug Fixes" },
  { type = "docs", section = "Documentation" },
  { type = "refactor", section = "Code Refactoring" },
]
# 忽略的提交信息前缀
ignore_commits = ["merge", "revert"]

[parser]
# 解析Conventional Commits的规则
conventional_commits = true
# 标题格式正则表达式
commit_title_pattern = "^(\\w+)(\\(.*\\))?:\\s(.*)$"

Docker Compose配置示例

创建docker-compose.yml实现便捷调用：

yaml
version: '3.8'

services:
  git-cliff:
    image: orhunp/git-cliff:latest
    volumes:
      - ./:/app  # 挂载项目目录
      - ~/.gitconfig:/root/.gitconfig  # 可选：挂载Git配置（如提交作者信息）
    command: generate --config cliff.toml --output CHANGELOG.md
    working_dir: /app

执行命令：

bash
docker-compose run --rm git-cliff

环境变量

可通过环境变量覆盖部分配置：

CI/CD集成示例（GitHub Actions）

在.github/workflows/changelog.yml中添加自动生成任务：

yaml
name: Generate Changelog
on:
  push:
    branches: [ main ]

jobs:
  generate-changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 获取完整Git历史
      
      - name: Run git-cliff via Docker
        run: |
          docker run --rm -v "$(pwd):/app" orhunp/git-cliff:latest generate --output CHANGELOG.md
      
      - name: Commit changes
        uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "docs: update CHANGELOG.md"
          file_pattern: CHANGELOG.md

常见问题

• Q: 提交记录未被识别？
  A: 确保提交信息符合Conventional Commits规范（如feat: add user authentication），或在cliff.toml中调整commit_types配置。

• Q: 如何自定义章节划分？
  A: 在cliff.toml的[git.commit_types]中定义提交类型与章节的映射关系。

• Q: 支持哪些输出格式？
  A: 默认支持Markdown，通过自定义模板可输出HTML、JSON等格式。