常规提交检查器

在 1.0.0 之前，可能会引入破坏性变更，而不会增加主版本号。

一个用于检查 Git 提交是否符合常规提交规范的通用工具和语言无关的实用程序。

为什么使用常规提交检查器？

• 无依赖项 - 提供了二进制下载，无需下载工具或解释器语言。
• 正确性 - 对常规提交规范的检查非常严格。其他检查器可能遗漏的许多违规行为都被捕获。
• 合理的默认值 - 默认情况下不应用主观检查规则，只声明符合常规提交规范。
• 可配置 - 虽然默认情况下不应用主观检查规则，但可以启用额外的主观检查规则。
• 快速 - 利用 Rust，性能显著优于其他解释性语言检查器。

即将推出

• 通过 CLI 参数使用可选的配置文件。
• 添加提交标题长度检查。
• 添加类型作为名词/非名词检查。
• 添加作用域作为名词/非名词检查。
• 在作用域前添加感叹号检查。
• 添加描述大小写检查。
• 添加类型大小写检查。
• 添加作用域大小写 CLI 检查。

内容

• 用法
  • 用法 - 额外标志
  • 用法 - Git 环境变量
  • 用法 - 记录
• CICD 示例
  • GitLab CI Rust 项目示例
    • 通过 Cargo
    • 通过二进制下载
  • Git Hooks Rust 项目示例
• 下载二进制文件
• 通过本地仓库编译
• 通过 Cargo 编译
• 单元测试
• 端到端测试
• 问题/功能请求

用法

传统提交检查器可以操作存储库历史中的Git提交范围，或者从标准输入读取提交信息。要使用标准输入提供提交信息，简单添加标志--from-stdin，标准输入将被读取。否则，要指定提交范围，可以添加--from-commit-hash <commit-hash>或--from-reference <reference>参数。提交范围从指定的提交开始，到包括HEAD为止。

提供的所有提交信息或范围内的提交都将与Conventional Commits v1.0.0规范进行校验。如果任何提交信息校验失败，则记录错误信息并退出程序，退出代码非零。

必需的参数是--from-stdin、--from-commit-hash <commit-hash>或--from-reference <reference>参数中的任何一个。

用法 - 额外标志

用法 - Git 环境变量

查找存储库时，会尊重Git环境变量。当${GIT_DIR}被设置时，它具有优先级，传统提交检查器将在${GIT_DIR}指定的目录中查找存储库。当${GIT_DIR}未设置时，传统提交检查器从当前目录开始查找存储库。

用法 - 记录

使用crate pretty_env_logger和log提供日志记录。可以使用环境变量RUST_LOG来设置日志级别。有关更详细的文档，请参阅https://crates.io/crates/pretty_env_logger。

CICD 示例

GitLab CI Rust 项目示例

通过 Cargo

有关通过Cargo安装的更多详细信息，请参阅通过Cargo编译。

注意 - 此示例下载最新的0.*版本。

conventional-commits-linting:
    stage: conventional-commits-linting
    image: rust
    before_script:
        - cargo install conventional_commits_linter --version ^0
    script:
        # Lint all the commits in the branch.
        - /usr/local/cargo/bin/conventional_commits_linter --from-reference "origin/${CI_MERGE_REQUEST_TARGET_BRANCH_NAME}" --allow-angular-type-only
    rules:
        - if: $CI_MERGE_REQUEST_ID

通过二进制下载

有关二进制下载的更多详细信息，请参阅下载二进制。

注意 - 此示例下载版本0.12.0。

conventional-commits-linting:
    stage: conventional-commits-linting
    image: rust
    before_script:
        - wget -q -O tmp.zip "https://gitlab.com/DeveloperC/conventional_commits_linter/-/jobs/artifacts/bin-0.12.0/download?job=release-binary-compiling-x86_64-linux-musl" && unzip tmp.zip && rm tmp.zip
    script:
        # Lint all the commits in the branch.
        - ./conventional_commits_linter --from-commit-hash "origin/${CI_MERGE_REQUEST_TARGET_BRANCH_NAME}" --allow-angular-type-only
    rules:
        - if: $CI_MERGE_REQUEST_ID

Git Hooks Rust 项目示例

一个示例commit-msg Git钩子，用于检查Rust项目的语义版本是否需要因为提交信息而增加。

#!/usr/bin/env bash

set -o errexit
set -o pipefail

# Lint new commit's message.
cat "${1}" | "${HOME}/.cargo/bin/conventional_commits_linter" --from-stdin --allow-angular-type-only

下载二进制文件

提供静态链接编译的二进制文件供下载。访问https://gitlab.com/DeveloperC/conventional_commits_linter/-/releases以查看所有发布版本，发布说明中包含各种架构的二进制下载链接。

如果您不信任提供的二进制文件，另一个选项是自行编译并使其可供远程下载，这样您的CI/CD等就可以下载它。

通过本地仓库编译

本地检查代码仓库，切换到仓库目录，然后使用 cargo 进行构建。使用 --release 标志可以生成优化后的二进制文件，但编译时间会更长。

git clone [email protected]:DeveloperC/conventional_commits_linter.git
cd conventional_commits_linter/
cargo build --release

编译后的二进制文件位于 target/release/conventional_commits_linter。

通过 Cargo 编译

Cargo 是 Rust 包管理器，使用 install 子命令从 crates.io 获取 Conventional Commits Linter 并本地编译二进制文件。 cargo install 将生成的二进制文件放置在 ${HOME}/.cargo/bin/conventional_commits_linter。

cargo install conventional_commits_linter

默认情况下，它会安装执行时的最新版本。您可以使用 --version 参数指定要安装的特定版本。对于某些环境，例如 CICD 等，您可能希望锁定版本。

例如：

cargo install conventional_commits_linter --version 0.12.0

与其锁定到特定版本，您还可以指定主版本或次版本。

例如：

cargo install conventional_commits_linter --version ^0

将下载最新的 0.* 版本，无论是 0.12.0 还是 0.23.0。

单元测试

单元测试套件包含一系列参数化测试，用于测试 Conventional Commits v1.0.0 的 linting，可以使用 cargo 设置和运行所有单元测试。

cargo test

端到端测试

为了确保正确性，由于存在各种进程外依赖项，项目使用 behave 框架（https://github.com/behave/behave）拥有端到端行为驱动测试套件。

要运行测试套件，您需要

• 编译 Convention Commits Linter 二进制文件。
• 安装 Python3。
• 安装 Behave。
• 执行 Behave。

注意 - 您不能使用 --release，因为测试套件使用 target/debug/conventional_commits_linter。

cargo build
cd conventional_commits_linter/end-to-end-tests/
virtualenv -p python3 .venv
source .venv/bin/activate
pip3 install -r requirements.txt
behave

问题/功能请求

要报告错误/问题或请求新功能，请使用 https://gitlab.com/DeveloperC/conventional_commits_linter/-/issues。