375 lines
10 KiB
Markdown
375 lines
10 KiB
Markdown
# GitVer
|
||
|
||
命令行版本管理工具，从 Git 仓库读取 tag 自动生成并回写版本号。
|
||
|
||
---
|
||
|
||
## 用法总览
|
||
|
||
```
|
||
gitver
|
||
gitver rewrite [PEType] [-f]
|
||
gitver setver=<pid> [repodir=<path>] [-test] [-setup=0|1]
|
||
gitver nuitkabuild=<pid> <mainPy> [repodir=<path>] [-test] [params="<nuitka参数>"]
|
||
gitver nuitkapydbuild=<pid> <modulePy> [repodir=<path>] [-test] [params="<nuitka参数>"]
|
||
gitver -setup=0|1 <pid> [repodir=<path>] [-test]
|
||
```
|
||
|
||
**通用参数说明：**
|
||
|
||
| 参数 | 说明 |
|
||
|---|---|
|
||
| `pid` | 产品 ID，整数，范围 0-65535，内嵌在命令名中（如 `setver=5`） |
|
||
| `repodir=<path>` | Git 仓库目录，缺省使用当前运行目录 |
|
||
| `-test` | 将产品版本号的 major/minor 置为 0（测试版本构建） |
|
||
| `params="..."` | 传递给 Nuitka 的额外参数，用双引号括起来 |
|
||
|
||
**BID 规则：**
|
||
`main`/`master` 分支固定 `bid=0`；其他分支格式须为 `<描述>.<数字>`，自动读取末尾数字作为 `bid`。
|
||
|
||
---
|
||
|
||
## 命令详解
|
||
|
||
### `gitver`（无参数交互模式）
|
||
|
||
自动读取当前分支最近三次符合 `<分支>.major.minor` 格式的 tag，提示用户选择 major+1 或 minor+1，二次确认后创建新 tag。
|
||
|
||
当前分支无有效 tag 时进入首发引导：提示输入默认 major/minor（回车使用默认 1/0），再创建首个 tag。
|
||
|
||
**交互示例（已有 tag）：**
|
||
|
||
```
|
||
当前分支: main，最近三个 tag：
|
||
main.1920.9
|
||
main.1920.10
|
||
main.1920.11
|
||
输入 1 → 创建 main.1921.0
|
||
输入 2 → 创建 main.1920.12
|
||
```
|
||
|
||
**交互示例（无 tag 首发）：**
|
||
|
||
```
|
||
未找到符合规则的历史标签
|
||
输入默认 major（回车=1）: 2
|
||
输入默认 minor（回车=0）: 5
|
||
→ 创建 <分支>.2.5
|
||
```
|
||
|
||
---
|
||
|
||
### `gitver rewrite`
|
||
|
||
自动识别当前目录源码类型（C++、C#、Python），执行默认版本回写。
|
||
|
||
```
|
||
gitver rewrite [PEType] [-f]
|
||
```
|
||
|
||
| 参数 | 说明 |
|
||
|---|---|
|
||
| `PEType` | 可选，`1`=EXE（默认），`2`=DLL，最多出现一次 |
|
||
| `-f` | 强制模式：未找到目标文件或回写失败仅提示，不返回错误码 35 |
|
||
|
||
**回写行为：**
|
||
|
||
- **C++**：递归查找首个 `.rc` 文件，回写 `FILEVERSION`、`PRODUCTVERSION`、`VALUE "FileVersion"`、`VALUE "ProductVersion"`（限定在 `VS_VERSION_INFO` 版本块内）
|
||
- **C#**：递归查找首个 `AssemblyInfo.cs`，回写 `AssemblyVersion`、`AssemblyFileVersion`
|
||
- **Python**：不执行回写，提示改用 `nuitkabuild=` 或 `nuitkapydbuild=`
|
||
|
||
**示例：**
|
||
|
||
```
|
||
gitver rewrite
|
||
gitver rewrite 2
|
||
gitver rewrite -f
|
||
```
|
||
|
||
---
|
||
|
||
### `gitver setver=<pid>`
|
||
|
||
从 Git 仓库读取 tag，生成产品版本号与文件版本号，并按源码类型自动回写。
|
||
|
||
```
|
||
gitver setver=<pid> [repodir=<path>] [-test] [-setup=0|1]
|
||
```
|
||
|
||
**版本号生成规则：**
|
||
|
||
- `ProductVersion = pid.bid.major.minor`（取当前分支前缀的最新 tag）
|
||
- `FileVersion = pid.yy.mmdd.id`（id = 当天当前分支提交次数）
|
||
|
||
**`-setup=N` 标志（打包模式）：**
|
||
|
||
存在 `-setup=N` 时，**不回写**版本信息到项目文件，改为：
|
||
1. 在 exe 目录或上级目录查找安装脚本
|
||
2. 修改脚本中的版本号字段
|
||
3. 调用对应编译器打包
|
||
|
||
| 值 | 脚本文件 | 编译器 |
|
||
|---|---|---|
|
||
| `0` | `setup.iss` | Inno Setup（`ISCC.exe`） |
|
||
| `1` | `setup.nsi` | NSIS（`makensis.exe`） |
|
||
|
||
**示例：**
|
||
|
||
```
|
||
gitver setver=5
|
||
gitver setver=5 repodir=E:\Code\OTH\gitver
|
||
gitver setver=5 -test
|
||
gitver setver=5 -setup=0
|
||
gitver setver=5 repodir=E:\Code\MyProj -setup=1
|
||
```
|
||
|
||
**输出示例：**
|
||
|
||
```
|
||
ProductVersion=5.0.1920.11
|
||
FileVersion=5.26.0519.3
|
||
```
|
||
|
||
**回写说明：**
|
||
|
||
- **C++**：回写 `.rc` 文件中的 FILEVERSION、PRODUCTVERSION 及对应字符串字段
|
||
- **C#**：回写 `AssemblyInfo.cs` 中的 AssemblyVersion、AssemblyFileVersion
|
||
- **Python**：仅输出版本号，不执行文件回写，提示改用 Nuitka 命令
|
||
- 编码：支持 ANSI/UTF-8（保留 UTF-8 BOM）；UTF-16 文件会报错停止
|
||
- 当前分支无匹配 tag 时自动使用默认版本 `1.0`
|
||
|
||
---
|
||
|
||
### `gitver nuitkabuild=<pid>`
|
||
|
||
生成版本号并调用 Nuitka 打包 Python 程序（EXE 模式）。
|
||
|
||
```
|
||
gitver nuitkabuild=<pid> <mainPy> [repodir=<path>] [-test] [params="<nuitka参数>"]
|
||
```
|
||
|
||
自动调用：
|
||
|
||
```
|
||
python -m nuitka --windows-product-version=<版本> --windows-file-version=<版本> <extra> <mainPy>
|
||
```
|
||
|
||
**示例：**
|
||
|
||
```
|
||
gitver nuitkabuild=5 main.py
|
||
gitver nuitkabuild=5 main.py -test
|
||
gitver nuitkabuild=5 src\app.py repodir=E:\Code\MyPyProj params="--standalone --output-dir=dist"
|
||
```
|
||
|
||
**输出示例：**
|
||
|
||
```
|
||
Nuitka 打包开始..
|
||
ProductVersion=5.0.1920.11
|
||
FileVersion=5.26.0519.3
|
||
```
|
||
|
||
> 需要当前环境已安装 Nuitka（可通过 `python -m nuitka --version` 验证）。
|
||
|
||
---
|
||
|
||
### `gitver nuitkapydbuild=<pid>`
|
||
|
||
生成版本号并调用 Nuitka 打包 Python 模块（pyd/DLL 模式）。
|
||
|
||
```
|
||
gitver nuitkapydbuild=<pid> <modulePy> [repodir=<path>] [-test] [params="<nuitka参数>"]
|
||
```
|
||
|
||
自动调用：
|
||
|
||
```
|
||
python -m nuitka --module --windows-product-version=<版本> --windows-file-version=<版本> <extra> <modulePy>
|
||
```
|
||
|
||
**示例：**
|
||
|
||
```
|
||
gitver nuitkapydbuild=5 module.py
|
||
gitver nuitkapydbuild=5 module.py -test
|
||
gitver nuitkapydbuild=5 src\core.py repodir=E:\Code\MyPyProj params="--output-dir=dist"
|
||
```
|
||
|
||
> 需要当前环境已安装 Nuitka（可通过 `python -m nuitka --version` 验证）。
|
||
|
||
---
|
||
|
||
### `gitver -setup=0|1`（独立打包命令）
|
||
|
||
独立调用安装脚本打包，不依赖 `setver=` 命令。
|
||
|
||
```
|
||
gitver -setup=0|1 <pid> [repodir=<path>] [-test]
|
||
```
|
||
|
||
**示例：**
|
||
|
||
```
|
||
gitver -setup=0 5
|
||
gitver -setup=1 5 repodir=E:\Code\MyProj
|
||
```
|
||
|
||
---
|
||
|
||
## 错误码
|
||
|
||
| 码 | 含义 |
|
||
|---|---|
|
||
| 2 | 默认回写流程下未获取到 git 提交号 |
|
||
| 3 | 参数非法或未知参数 |
|
||
| 4 | `setver=` 的 pid 非法 |
|
||
| 5 | `setver=` 无法根据分支名计算 bid |
|
||
| 9 | `setver=` 获取当天分支提交次数失败 |
|
||
| 15 | 回写流程未识别源码类型 |
|
||
| 16 | 回写流程识别到 Python，请改用 nuitka 命令 |
|
||
| 17 | `nuitkabuild=` 参数不足（缺少 mainPy） |
|
||
| 18 | `nuitkabuild=` 的 pid 非法 |
|
||
| 19 | `nuitkabuild=` 无法根据分支名计算 bid |
|
||
| 21 | `nuitkabuild=` 获取当天分支提交次数失败 |
|
||
| 22 | `rewrite` 参数非法（PEType 非法或重复） |
|
||
| 23 | `repodir=` 不是有效目录 |
|
||
| 24 | `nuitkapydbuild=` 参数不足（缺少 modulePy） |
|
||
| 25 | `nuitkapydbuild=` 的 pid 非法 |
|
||
| 26 | `nuitkapydbuild=` 无法根据分支名计算 bid |
|
||
| 28 | `nuitkapydbuild=` 获取当天分支提交次数失败 |
|
||
| 29 | 无参数模式下无法获取当前分支 |
|
||
| 30 | 无参数模式下读取标签列表失败 |
|
||
| 31 | 无参数模式下未读取到用户输入 |
|
||
| 32 | 无参数模式下用户选择非法，或 major/minor 已达上限 |
|
||
| 33 | 无参数模式下创建 tag 失败 |
|
||
| 34 | 无参数模式下创建 tag 后校验失败 |
|
||
| 35 | 未找到可回写目标文件，或回写失败 |
|
||
| 36 | `-setup=` 值不支持（仅支持 0 和 1） |
|
||
| 37 | 未找到安装脚本（setup.iss / setup.nsi） |
|
||
| 38 | 修改安装脚本失败 |
|
||
| 39 | 未找到安装编译器（ISCC.exe / makensis.exe） |
|
||
|
||
---
|
||
|
||
## 最小自测
|
||
|
||
### 基础验证：`setver=`
|
||
|
||
```bash
|
||
# 初始化测试仓库
|
||
mkdir test_repo && cd test_repo
|
||
git init
|
||
echo test > README.txt
|
||
git add . && git commit -m "init"
|
||
git tag main.1920.10
|
||
git tag main.1920.11
|
||
|
||
# 验证版本生成
|
||
gitver setver=5
|
||
# 预期:
|
||
# ProductVersion=5.0.1920.11
|
||
# FileVersion=5.yy.mmdd.<id>
|
||
# 返回码: 0
|
||
```
|
||
|
||
### 验证无 tag 时自动使用默认版本
|
||
|
||
```bash
|
||
git checkout -b newbranch
|
||
gitver setver=5
|
||
# 预期: ProductVersion=5.<bid>.1.0（无 tag 自动回落默认 1.0）
|
||
# 返回码: 0
|
||
```
|
||
|
||
### 验证分支 tag 隔离
|
||
|
||
```bash
|
||
git checkout -b feature.12
|
||
git tag feature.12.1930.7
|
||
git tag feature.12.1930.8
|
||
gitver setver=5
|
||
# 预期: ProductVersion=5.12.1930.8（忽略 main.* tag）
|
||
# 返回码: 0
|
||
```
|
||
|
||
### 验证 `-test`
|
||
|
||
```bash
|
||
gitver setver=5 -test
|
||
# 预期: ProductVersion=5.0.0.0（major/minor 置零）
|
||
# 返回码: 0
|
||
```
|
||
|
||
### 验证 `nuitkabuild=`
|
||
|
||
```bash
|
||
gitver nuitkabuild=5 main.py
|
||
# 预期: 调用 python -m nuitka，注入版本号参数
|
||
|
||
gitver nuitkabuild=5 src\app.py params="--standalone --output-dir=dist"
|
||
# 预期: 额外参数传递给 Nuitka
|
||
```
|
||
|
||
### 验证 `-setup=`
|
||
|
||
```bash
|
||
# 确保 exe 目录或上级目录有 setup.iss
|
||
gitver setver=5 -setup=0
|
||
# 预期: 修改 setup.iss 中的版本号并调用 ISCC.exe 编译
|
||
```
|
||
|
||
---
|
||
|
||
## 回归清单
|
||
|
||
### rewrite 组
|
||
|
||
| 命令 | 预期返回码 |
|
||
|---|---|
|
||
| `gitver rewrite` | 0 / 15 / 16 / 35 |
|
||
| `gitver rewrite -f` | 0 / 15 / 16 |
|
||
| `gitver rewrite 2` | 0 / 15 / 35 |
|
||
| `gitver rewrite 1 2` | 22 |
|
||
|
||
### setver= 组
|
||
|
||
| 命令 | 预期返回码 |
|
||
|---|---|
|
||
| `gitver setver=5` | 0 |
|
||
| `gitver setver=5 -test` | 0 |
|
||
| `gitver setver=5 repodir=E:\NotExists` | 23 |
|
||
| `gitver setver=5 -setup=0` | 0 / 37 / 38 / 39 |
|
||
| `gitver setver=5 -setup=9` | 36 |
|
||
| `gitver setver=abc` | 4 |
|
||
|
||
### nuitkabuild= 组
|
||
|
||
| 命令 | 预期返回码 |
|
||
|---|---|
|
||
| `gitver nuitkabuild=5 main.py` | 0 / 19 / 21 |
|
||
| `gitver nuitkabuild=5 main.py -test` | 0 |
|
||
| `gitver nuitkabuild=5 main.py params="--standalone"` | 0 |
|
||
| `gitver nuitkabuild=5 main.py repodir=E:\NotExists` | 23 |
|
||
| `gitver nuitkabuild=5` | 17 |
|
||
|
||
### nuitkapydbuild= 组
|
||
|
||
| 命令 | 预期返回码 |
|
||
|---|---|
|
||
| `gitver nuitkapydbuild=5 module.py` | 0 / 26 / 28 |
|
||
| `gitver nuitkapydbuild=5 module.py -test` | 0 |
|
||
| `gitver nuitkapydbuild=5 module.py params="--output-dir=dist"` | 0 |
|
||
| `gitver nuitkapydbuild=5 module.py repodir=E:\NotExists` | 23 |
|
||
| `gitver nuitkapydbuild=5` | 24 |
|
||
|
||
> **注意**：如果打包时提示“未找到安装编译器（ISCC.exe / makensis.exe）”，请手动下载安装对应工具，并将其可执行文件路径（如 `ISCC.exe` 或 `makensis.exe` 所在目录）添加到系统环境变量 `PATH`。常见下载地址：
|
||
>
|
||
> - Inno Setup: https://jrsoftware.org/isinfo.php
|
||
> - NSIS: https://nsis.sourceforge.io/Download
|
||
>
|
||
> 添加方法：
|
||
> 1. 复制编译器安装目录路径（如 `C:\Program Files (x86)\Inno Setup 6`）。
|
||
> 2. 打开“系统属性”→“高级”→“环境变量”，在“系统变量”中找到 `PATH`，点击“编辑”，添加上述路径。
|
||
> 3. 重新打开命令行窗口后再运行打包命令。
|