91 lines
3.3 KiB
Markdown
91 lines
3.3 KiB
Markdown
# Git 集成设计（GitIntegration）
|
||
|
||
## 一、目标与原则
|
||
|
||
### 1.1 目标
|
||
|
||
- 让调用方无需手动执行 `git add/commit` 也能得到规范提交
|
||
- 将“进度节点”与“提交记录”关联：在状态历史中记录 `git_commit`（可为空）
|
||
|
||
### 1.2 原则
|
||
|
||
- **静默即成功**：Git 正常执行时尽量不输出额外信息
|
||
- **.aide 默认不进提交**：Git 记录的是代码/文档等实际产出，状态文件仅做本地追踪
|
||
- **无变更可提交 ≠ 失败**：当工作区没有可提交变更时，本次记录仍然成功，`git_commit = null`
|
||
|
||
## 二、提交信息生成规则（必须一致）
|
||
|
||
提交信息格式以 `aide-program/docs/formats/data.md` 的“Git 提交信息格式”为准。
|
||
|
||
核心模板：
|
||
|
||
- 普通：`[aide] <phase>: <summary>`
|
||
- issue：`[aide] <phase> issue: <description>`
|
||
- error：`[aide] <phase> error: <description>`
|
||
- back-step：`[aide] <phase> back-step: <reason>`
|
||
- back-part：`[aide] <phase> back-part: <reason>`
|
||
|
||
> 说明：`phase` 使用“动作完成后的 current_phase”，以保证 status 与 commit message 一致。
|
||
|
||
## 三、暂存（add）策略
|
||
|
||
默认策略（与现有文档保持一致）：
|
||
|
||
- 执行 `git add .`（由 `.gitignore` 控制忽略项）
|
||
|
||
可选增强（建议实现时评估，避免误提交）：
|
||
|
||
- 仅暂存已跟踪文件：等价于“只更新 tracked 的变更”
|
||
- 在提交前检查 `git status`，对明显异常（如大量生成文件）给出 `⚠` 提示
|
||
|
||
## 四、事务边界（状态与 Git 的一致性）
|
||
|
||
### 4.1 推荐边界
|
||
|
||
一次 `aide flow` 调用视为一个“原子动作”：
|
||
|
||
- 校验失败/关键 Hook 失败：不应推进状态，也不应提交
|
||
- Git 必须但执行失败：不应推进状态（避免“状态已前进但提交缺失”）
|
||
- 无变更可提交：允许推进状态，`git_commit = null`
|
||
|
||
### 4.2 “无变更可提交”的判定
|
||
|
||
当出现“nothing to commit / working tree clean”等语义时：
|
||
|
||
- 视为成功，不返回错误
|
||
- 仍写入状态历史，但 `git_commit` 为空
|
||
|
||
## 五、失败与降级策略
|
||
|
||
### 5.1 非 git 仓库
|
||
|
||
若当前目录不在 git 仓库内：
|
||
|
||
- **默认建议：失败**（提示用户初始化 git 或切换到正确目录）
|
||
- 可配置降级：仅记录状态，不做 git（见 5.3）
|
||
|
||
### 5.2 git 命令不可用/异常
|
||
|
||
若 git 不存在或执行报错：
|
||
|
||
- 默认失败，并输出具体错误与建议
|
||
|
||
### 5.3 可配置项（建议加入 flow 配置）
|
||
|
||
为满足不同团队习惯，建议在 `flow` 下增加可选配置（若不实现则使用默认行为）：
|
||
|
||
| 配置键（建议） | 类型 | 默认值（建议） | 说明 |
|
||
|---|---:|---:|---|
|
||
| `flow.git.enabled` | bool | true | 是否启用 Git 集成 |
|
||
| `flow.git.required` | bool | true | 启用后是否“必须成功”，否则降级为仅记录 |
|
||
| `flow.git.allow_empty_commit` | bool | false | 是否允许创建空提交（用于记录纯流程节点） |
|
||
| `flow.git.add_strategy` | string | `"dot"` | 暂存策略：`dot`（git add .）/ 其它策略（可扩展） |
|
||
|
||
> 若 `allow_empty_commit = true`，则“无变更”场景也会产生 commit；需要评估对仓库历史的影响。
|
||
|
||
## 六、与 Hooks 的顺序关系
|
||
|
||
会产生/修改文件的钩子（如 PlantUML 生成 PNG）必须在 Git add/commit 之前执行，否则生成物不会进入本次提交。
|
||
|
||
详细触发点见：`aide-program/docs/commands/flow/hooks.md`
|