thegeeklab/git-sv

git-sv

基于约定式提交的Git语义化版本控制工具。


镜像概述和主要用途

git-sv是一款基于约定式提交的Git语义化版本控制工具，能够根据Git提交消息自动生成语义化版本号、创建Git标签、生成发布说明和变更日志，帮助开发者规范化版本管理流程。

核心功能和特性

• 基于提交类型自动识别版本变更（主版本、次版本、补丁版本）
• 支持自定义版本更新规则和标签格式
• 生成结构化的发布说明和变更日志
• 提供提交消息验证和辅助功能
• 支持多环境配置和模板自定义
• 兼容主流CI系统和Git工作流

安装

提供适用于Linux和macOS的预构建多架构二进制文件。

Shell
# Linux amd64
curl -SsfL https://github.com/thegeeklab/git-sv/releases/latest/download/git-sv-linux-amd64 -o ~/.local/bin/git-sv
chmod +x ~/.local/bin/git-sv

Shell
# macOS arm
curl -SsfL https://github.com/thegeeklab/git-sv/releases/latest/download/git-sv-darwin-10.12-arm64 -o ~/.local/bin/git-sv
chmod +x ~/.local/bin/git-sv

Shell
# macOS intel
curl -SsfL https://github.com/thegeeklab/git-sv/releases/latest/download/git-sv-darwin-10.12-amd64 -o ~/.local/bin/git-sv
chmod +x ~/.local/bin/git-sv

在macOS上，还可以使用homebrew安装：

Shell
brew tap thegeeklab/tap
brew install git-sv

构建

使用以下命令从源代码构建二进制文件：

Shell
make build

配置

配置从YAML文件按以下顺序加载（后加载的配置覆盖前者）：

• 内置默认配置
• 仓库根目录下的.gitsv/config.yaml或.gitsv/config.yml（找到的第一个）

要查看默认配置，请运行：

Shell
git sv cfg default

Yaml
versioning:
  update-major: [] # 用于更新主版本号的提交类型。
  update-minor: [feat] # 用于更新次版本号的提交类型。
  update-patch: [build, ci, chore, fix, perf, refactor, test] # 用于更新补丁版本号的提交类型。
  # 当提交类型不在更新规则中且为未知类型（未映射到提交消息类型）时；
  # 若ignore-unknown=false则更新补丁版本，若ignore-unknown=true则不更新版本。
  ignore-unknown: false

tag:
  pattern: "%d.%d.%d" # 用于创建Git标签的格式。
  filter: "" # 允许使用Git模式语法过滤需要考虑的标签。

release-notes:
  sections: # 发布说明的每个部分数组。有关更多信息，请查看模板部分。
    - name: Features # 部分名称。
      section-type: commits # 部分类型，支持的类型：commits、breaking-changes。
      commit-types: [feat] # 提交部分类型的提交类型，一种提交类型不能出现在多个部分中。
    - name: Bug Fixes
      section-type: commits
      commit-types: [fix]
    - name: Breaking Changes
      section-type: breaking-changes

branches: # Git分支配置。
  prefix: ([a-z]+\/)? # 分支名称的前缀，应为正则表达式组。
  suffix: (-.*)? # 分支名称的后缀，应为正则表达式组。
  disable-issue: false # 如果不需要从分支名称恢复问题ID，设置为true。
  skip: [master, main, developer] # 提交消息验证时忽略的分支名称列表。
  skip-detached: false # 如果在分离头指针状态下应忽略提交消息验证，设置为true。

commit-message:
  # 支持的提交类型。
  types: [
      build,
      ci,
      chore,
      docs,
      feat,
      fix,
      perf,
      refactor,
      revert,
      style,
      test,
    ]
  header-selector: "" # 可以在此处放置正则表达式以仅选择提交消息的特定部分。请定义一个名为'header'的正则表达式组。
  scope:
    # 定义支持的作用域，如果为空，则不验证作用域；如果非空，则仅支持列出的作用域。
    # 如果需要定义作用域并保持其可选性，请在列表中添加""。
    values: []
  footer:
    issue: # 如果希望禁用问题页脚，请使用"issue: {}"。
      key: jira # 用于定义页脚元数据中问题的名称。
      key-synonyms: [Jira, JIRA] # 页脚元数据支持的变体。
      use-hash: false # 如果为false，使用": "作为分隔符；如果为true，使用" #"作为分隔符。
      add-value-prefix: "" # 为问题值添加前缀。
  issue:
    regex: "[A-Z]+-[0-9]+" # 问题ID的正则表达式。

模板

git-sv使用_go templates_格式化release-notes和changelog的输出，要查看默认模板配置，请查看https://github.com/thegeeklab/git-sv/tree/main/templates/assets%E3%80%82%E5%8F%AF%E4%BB%A5%E9%80%9A%E8%BF%87%E5%9C%A8%E4%BB%93%E5%BA%93%E4%B8%AD%E6%B7%BB%E5%8A%A0%60.gitsv/templates%60%E6%9D%A5%E8%A6%86%E7%9B%96%E9%BB%98%E8%AE%A4%E9%85%8D%E7%BD%AE%E3%80%82

Shell
.gitsv
└── templates
    ├── changelog-md.tpl
    └── releasenotes-md.tpl

.gitsv/templates中的所有内容都会被加载，因此可以根据需要添加更多文件。

变量

执行模板时，releasenotes-md.tpl将接收单个ReleaseNote变量，changelog-md.tpl将接收ReleaseNote列表变量。

每个ReleaseNoteSection将根据配置文件中的release-notes.section进行配置。各部分的顺序将保持不变，SectionType根据section-type属性定义，如下表所示：

:warning: 当前仅支持commits和breaking-changes作为section-types，使用其他值将导致该部分从模板变量中移除。

使用

使用--help或-h获取使用信息，请注意某些命令有独特的选项：

Shell
$ git-sv --help
NAME:
   git-sv - Git语义化版本工具。

USAGE:
   git-sv [全局选项] 命令 [命令选项] [参数...]

VERSION:
   20e64f8

COMMANDS:
   config, cfg                   命令行配置
   current-version, cv           从Git获取最新发布的版本
   next-version, nv              根据Git提交消息生成下一个版本
   commit-log, cl                按范围以JSON格式列出所有提交日志
   commit-notes, cn              根据范围生成提交说明
   release-notes, rn             生成发布说明
   changelog, cgl                生成变更日志
   tag, tg                       根据Git提交消息生成带版本的标签
   commit, cmt                   使用约定式提交消息助手执行git commit
   validate-commit-message, vcm  用作prepare-commit-message钩子以验证和增强提交消息
   help, h                       显示命令列表或单个命令的帮助

GLOBAL OPTIONS:
   --help, -h     显示帮助
   --version, -v  打印版本

如果git-sv已配置在PATH中，也可以像Git命令一样使用：

Shell
git sv
git sv current-version
git sv next-version

范围

commit-log和commit-notes等命令具有范围选项。支持的范围类型：tag、date和hash。

默认情况下，git log使用--date=short，所有返回的日期格式为YYYY-MM-DD。

范围tag如果start为空，将使用git for-each-ref refs/tags获取最后一个可用标签，其他类型不使用现有标签。对于具有大量提交的旧仓库，建议始终设置起始限制。

范围date使用git log的--since和--until。可以使用git log支持的所有格式。如果end为YYYY-MM-DD格式，sv将在git log命令中添加一天以使结束日期包含在内。

范围tag和hash用于git log的修订范围。如果end为空，将使用HEAD代替。

Shell
# 使用包含范围以JSON格式获取提交日志
git-sv commit-log --range hash --start 7ea9306~1 --end c444318

# 返回最后一个标签之后的所有提交
git-sv commit-log --range tag

CI系统

为了使git-sv正常工作，必须存在Git标签信息。某些CI系统在克隆时默认省略标签，可能需要手动获取标签。

Woodpecker CI

默认的克隆插件会跳过标签。可以通过以下方法之一更改此行为：

• 使用plugins/git-clone时定义自定义克隆步骤并设置tags: true
• 在命令中执行手动克隆

贡献者

特别感谢所有https://github.com/thegeeklab/git-sv/graphs/contributors%E3%80%82%E5%A6%82%E6%9E%9C%E6%82%A8%E6%83%B3%E8%B4%A1%E7%8C%AE%EF%BC%8C%E8%AF%B7%E5%8F%82%E9%98%85https://github.com/thegeeklab/git-sv/blob/main/CONTRIBUTING.md%E3%80%82

本项目是Beatriz Vieira的https://github.com/bvieira/sv4git%E7%9A%84%E5%88%86%E6%94%AF%E3%80%82%E6%84%9F%E8%B0%A2%E6%82%A8%E7%9A%84%E5%B7%A5%E4%BD%9C%E3%80%82

许可证

本项目采用MIT许可证 - 详见https://github.com/thegeeklab/git-sv/blob/main/LICENSE%E6%96%87%E4%BB%B6%E3%80%82