# 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 |