Git Hooks 配置结构

gvt hook 通过 .gvt/hook/ 目录管理检查配置，按模块拆分独立 .toml。

目录布局

.gvt/
├── hook.toml                    # 通用全局配置（固定文件，与 hook/ 同级）
└── hook/
    ├── backend/
    │   └── backend.toml         # Go 后端
    ├── frontend/
    │   ├── admin.toml           # 管理后台
    │   └── portal.toml          # 门户前端
    └── modules/
        └── <name>.toml          # gvt add 注册的动态模块

全局配置

通用全局配置固定放在 .gvt/hook.toml（位于 .gvt/ 下、与 hook/ 目录同级）：

# false 时跳过所有检查
enabled = true

# 是否在收集待检查文件时按项目 .gitignore 跳过被忽略的路径（默认 true）
gitignore_filter = true

# 作为 .gitignore 补充的额外忽略列表（收集阶段即跳过）
# 目录前缀 "dist/" / 精确路径 "frontend/portal/src/api/" / glob "*.gen.ts"
extra_ignore = ["dist/", "frontend/portal/src/api/", "*.gen.ts"]

• gitignore_filter：开启后 all 模式 walk 不遍历被忽略大目录，changed/staged 模式剔除已跟踪后加入 .gitignore 的散文件；git 不可用时优雅降级。
• 兼容旧路径：.gvt/hook.toml 不存在时回退读取 .gvt/hook/config.toml（仅 enabled）。

模块配置

.gvt/hook/backend/backend.toml：

enabled = true
dir = "."
module_type = "backend"
warn_lines = 250
max_lines = 300
check_order = ["format", "line_count", "go_vet", "go_build", "staticcheck"]

.gvt/hook/frontend/portal.toml（Vue 3）：

enabled = true
dir = "frontend/portal"
module_type = "frontend"
framework = "vue3"
warn_lines = 250
max_lines = 300
check_order = ["line_count", "lint", "build", "format", "inline_styles_block", "vue-types", "error_handling"]

字段说明

字段	说明
enabled	是否启用该模块检查
dir	检查根目录（相对模块 .toml 所在目录）
module_type	模块类型：backend / frontend
framework	前端框架：vue3 / react（仅前端模块）
warn_lines	行数警告阈值
max_lines	行数错误阈值（超限则失败）
check_order	检查项执行顺序（可任意组合）
go_build.entries	后端编译入口（可选，公共库无需配置）
go_nilaway	NilAway 空指针检测（默认开启，可关闭）

go_build.entries（可选）

后端模块的 [go_build] 检查支持可选的 [[go_build.entries]] 子配置，用于声明多个可独立编译的入口：

[go_build]
enabled = true
command = "go"
args = ["build", "./..."]

# 仅多入口项目需要声明，公共库（无 main 包）无需配置
[[go_build.entries]]
name = "server"
path = "cmd/server"
output = "server"

• 有 entries：逐个执行 go build <entry.path> 校验入口编译
• 无 entries：自动回退到 command / args（默认 go build ./...），编译全部包

gvt add 注册后端模块时会自动探测 cmd/ 下的 main.go 并生成 entries；公共库无 main 包时不生成 entries，go_build 自动使用 go build ./...。

动态模块（gvt add）

使用 gvt add --dir <path> 注册任意目录，自动检测工具链并写为 .gvt/hook/modules/<name>.toml。文件名由路径推导：

• . → 项目名
• 多层路径用 - 连接，如 frontend/my-app → frontend-my-app

规范文档生成

gvt add 注册模块后自动生成规范文档（CONVENTIONS.md）到模块目录。修改配置后手动运行：

gvt doc          # 重新生成所有已启用模块的规范文档
gvt doc backend  # 只为后端模块生成

gvt doc 不带参数时覆盖所有模块，也可指定单个模块名（通过 gvt ls 查看）。文档始终覆盖写入，内容反映当前配置的所有检查项与阈值。详见 gvt doc。

注意事项

• 每个模块独立 enabled 开关，可单独关闭某目录检查。
• 修改配置后无需重启，下次 gvt hook 自动读取最新内容。