# Git Workflow

> 创建或调整分支、工作树、提交和拉取请求，处理评审反馈、合并或改写历史时使用；遵守任务授权与交付约束。

- Skill: `ben2pc/git-workflow` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ben2pc/git-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ben2pc/git-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: ben2pc (https://skillmd.com/u/ben2pc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ben2pc/git-workflow

---


# Git 生命周期

`git-workflow` 保存团队特有的交付契约和远端操作边界。纯只读查询不触发本技能；改变状态时读取适用约束。Hook 执行确定性门禁，常规命令由模型选择。

## 核心约束

1. **按操作核对现场。** 只检查当前动作依赖的仓库、工作树、分支或远端状态；关键现场变化时刷新相关信息，不把一次检查当作永久有效，也不逐步重复整套调查。
2. **保护已有改动。** 无法确认归属的改动默认属于用户；不覆盖、不移动、不提交，也不通过暂存、清理或切换命令隐藏它们。
3. **分支先行。** 不直接提交默认分支。新工作从仓库约定的最新基准分支开始；已有正确任务分支时继续使用，不机械重建。
4. **提交表达一个逻辑变化。** 按语义边界提交，验证强度与风险匹配；不要把无关关注点塞进同一提交。
5. **拉取请求正文保持当前事实。** 评论记录过程，正文记录最终范围、验收和验证，以及必要的决定、风险与后续事项。
6. **复用范围内授权。** “准备并创建草稿请求”覆盖必要的提交、推送与创建；“修复当前请求”覆盖范围内修复、验证、推送和正文更新。已有授权持续有效，不因阶段切换再次询问；不能据此推断已授权进入 Ready、合并、部署、评论或其他对外沟通。共享历史改写须有明确授权。

## 1. 操作前检查

- 首次定位目标时核实仓库根，不根据目录名猜测；切换分支或写入前检查当前分支、工作树状态和未提交改动，提交前核对暂存范围。
- 新建分支或比较差异时确认实际基准，不写死为 `main`；远端写入前核对远端仓库、目标分支或拉取请求及预期提交。切换仓库、分支、目标或有其他写入者活动后，刷新受影响的现场。
- 未提交或未跟踪内容先判断能否隔离；不能安全隔离时停止并说明冲突。未经明确授权，不执行 `git stash`、`git reset --hard`、`git checkout --`、`git clean` 或对共享分支强制推送。
- 多个写入任务并行时按 `incremental-impl` 判断隔离方式，优先独立 worktree；共享工作树须同时核实文件与共享状态隔离。新建工作树显式指定基准，创建或切换时检查占用关系。单写入任务不为形式额外创建 worktree。

## 2. 提交与历史

- 在一个能用一句话描述的逻辑变化完成后提交；高风险删除、批量替换或依赖升级前，可先建立安全检查点。
- 提交信息使用 Conventional Commits：

```text
<type>(<scope>): <摘要>
```

允许的 `type`：`feat`、`fix`、`docs`、`refactor`、`chore`、`test`、`perf`、`style`、`build`、`ci`、`revert`。

- 正文只在动机、关键决定或限制不明显时补充，解释为什么，不复述差异。
- 临时检查点可以使用 `fixup` 或可识别的临时前缀，但在需要保留逐提交历史的仓库中，进入 Ready 前应整理。
- 是否整理历史取决于仓库合并策略和分支是否已共享。采用压缩合并时不为表面整洁重写本地历史；改写共享历史前必须获得团队确认。

## 3. 按当前阶段读取拉取请求流程

执行拉取请求操作前，读取 `references/pull-requests.md` 中对应章节：创建或更新草稿请求、进入待评审状态、处理评审与持续集成反馈、合并。只处理当前授权阶段，保留各阶段的远端读回、资料生命周期和交付证据要求。

## 机制边界

| 机制 | 保证什么 |
|---|---|
| `commit-reminder` | 未提交变化增长时提醒在下一个语义边界提交 |
| `pr-create-guard` | 创建后展示标题与正文结构，提醒修正漂移 |
| `pr-ready-guard` | 阻止未清理的临时规范和未推送提交进入 Ready |
| `pr-merge-guard` | 阻止验收标准或验证计划仍有未完成事项的拉取请求合并 |