git-semver Docker镜像文档

镜像概述

git-semver是一款从git标签生成符合语义化版本（SemVer）规范的工具。它解决了git describe输出非SemVer兼容、版本排序异常等问题，能够根据git仓库的标签和提交历史，自动生成合规的版本号，适用于通过git标签进行软件版本管理的场景。

核心功能与特性

• SemVer合规性：将git标签转换为符合语义化版本规范的版本号，支持<major>.<minor>.<patch>核心结构及预发布标识、构建元数据
• 未标签提交处理：对未直接标签的提交，自动生成包含提交数（dev.N）和提交哈希的开发版本（如3.5.2-dev.22+baf822dd）
• 版本格式自定义：通过命令行选项控制输出格式，支持排除次要/补丁版本、预发布标识、构建元数据，设置版本前缀等
• 容器化部署：提供Docker镜像，无需本地安装依赖，直接通过容器运行，简化跨环境使用

使用场景

• 软件版本管理：适用于使用git标签标记版本的项目，自动生成规范版本号
• CI/CD流程集成：在持续集成/部署中自动生成版本，用于构建、发布等环节
• 版本排序需求：解决git describe输出无法正确排序的问题，确保版本号符合SemVer precedence规则

使用方法

Docker基本使用

通过Docker容器运行git-semver，需挂载当前git仓库目录至容器内的/git-semver路径：

sh
# 生成当前仓库的语义化版本号
docker run --rm -v $(pwd):/git-semver mdomke/git-semver

参数说明：

• --rm：容器退出后自动删除
• -v $(pwd):/git-semver：将当前目录（git仓库根目录）挂载到容器内的工作目录，确保工具能访问git仓库数据

命令行选项

通过命令行选项控制版本输出格式，常用选项如下：

使用示例

sh
# 基本使用：生成包含预发布标识和哈希的版本
docker run --rm -v $(pwd):/git-semver mdomke/git-semver
# 输出示例：3.5.2-dev.22+baf822dd

# 排除构建元数据
docker run --rm -v $(pwd):/git-semver mdomke/git-semver -no-meta
# 输出示例：3.5.2-dev.22

# 仅保留主版本和次版本
docker run --rm -v $(pwd):/git-semver mdomke/git-semver -no-patch
# 输出示例：3.5

# 添加前缀并排除哈希
docker run --rm -v $(pwd):/git-semver mdomke/git-semver -prefix v -no-hash
# 输出示例：v3.5.2

# 设置自定义元数据
docker run --rm -v $(pwd):/git-semver mdomke/git-semver -set-meta custom
# 输出示例：3.5.2+custom

版本标签规范

git-semver基于git标签生成版本，标签需符合以下格式：

• 核心版本：<major>.<minor>.<patch>（如1.2.3）
• 可选前缀：可添加v前缀（如v2.3.0）
• 预发布标识：通过连字符添加（如1.1.0-rc3）

示例标签创建：

sh
git tag v2.0.0-rc1  # 创建带预发布标识的标签

版本生成逻辑对比

git-semver与git describe的输出对比：

（注：git-semver会自动递增补丁版本，并添加dev.N预发布标识，其中N为自上次标签后的提交数）