git-workflow

1# Git 工作流助手
2 
3## 核心原则
4 
5- 只执行用户明确要求的 Git 动作。生成提交信息不等于暂存或提交；提交不等于推送；创建 PR 不等于合并 PR、关闭 Issue 或发布 Release。
6- 把工作树中已有、未跟踪和无关的修改视为用户资产，不覆盖、不回退、不混入本轮提交。
7- 优先使用非交互命令。涉及历史重写、冲突选择或远程覆盖时降低自动化程度。
8 
9## 工作流程
10 
11### 1. 读取仓库规则与状态
12 
13先阅读适用的 `AGENTS.md`、`CONTRIBUTING.md`、README、提交规范和 CI 说明，再检查：
14 
15```bash
16git status --short --branch
17git diff
18git diff --cached
19git log --oneline -10
20git remote -v
21git branch -vv
22```
23 
24同时识别未跟踪文件、当前分支、upstream、远程差异和已有失败。不得只看 staged diff。
25 
26### 2. 明确动作与文件范围
27 
28把用户请求拆成独立授权：
29 
30| 动作 | 默认权限 |
31|------|----------|
32| 分析状态、生成 commit message 或 PR 文案 | 只读 |
33| 暂存、commit | 仅用户要求后执行，只选本轮相关文件 |
34| 创建或切换分支 | 仅用户明确要求时执行；实现流程需要但未获授权时，先说明原因并取得同意 |
35| fetch、push、创建 PR | 分别确认在请求范围内，不互相推导 |
36| merge、关闭 Issue、发布 Release | 必须有明确授权 |
37| rebase、修改已发布历史、强制更新远程 | 高风险，必须明确授权并满足额外条件 |
38 
39存在无关改动时不得使用 `git add .` 或 `git add -A`。逐个暂存目标文件，并用 `git diff --cached` 复核。
40 
41### 3. 规划原子提交
42 
43- 根据真实 diff 判断 `feat`、`fix`、`docs`、`refactor`、`test`、`perf` 或 `chore`。
44- 沿用仓库近期提交的语言、scope 和格式。
45- 一个提交只表达一项可独立理解和验证的改动。
46- `Closes #123` 仅在对应 Issue 确实应由该提交自动关闭时使用。
47 
48提交信息遵循：
49 
50```text
51<type>(<scope>): <简短描述>
52 
53<必要时说明原因、关键实现和兼容性>
54 
55<关联 Issue 或 Breaking Change>
56```
57 
58### 4. 验证后执行
59 
60提交前先检查验证脚本是否会下载依赖、访问外部服务或产生其他状态，再运行与改动相关的测试、lint、构建或文档检查，并记录实际命令和退出状态。可能产生外部副作用时先取得授权。基线已有失败时单独说明，不能把未运行的项目标为通过。
61 
62执行 commit 后检查：
63 
64```bash
65git status --short --branch
66git show --stat --oneline HEAD
67```
68 
69推送前先 `git fetch`，确认 upstream 没有未整合的新提交；禁止 force push。
70 
71### 5. 创建 PR
72 
73PR 文案应帮助 reviewer 结合 diff 和验证结果快速审查，至少包含：
74 
75```markdown
76## 变更摘要
77 
78## 关键改动
79 
80## 验证结果
81 
82## 风险与回滚
83…