Git故事化提交策略Skill git-storytelling-commit-strategy

---

名称: git-storytelling-commit-strategy 描述: 用于规划提交策略或确定何时提交更改。帮助开发者及早且频繁提交，以讲述他们的开发过程故事。 允许的工具:

• 读取
• 写入
• 编辑
• Bash
• Grep
• Glob

---

Git 故事化提交策略

这个技能帮助您理解和实施有效的提交策略，通过小而聚焦的提交来讲述您的开发过程故事。

关键概念

及早提交，频繁提交

在开发过程中进行小而频繁的提交，而不是大型、不频繁的提交。这种方法：

• 创建详细的思考过程历史
• 使理解更改更容易
• 简化调试和回滚更改
• 支持更好的代码审查
• 讲述解决方案如何演变的故事

原子提交

每个提交应代表一个单一的逻辑更改：

• 一个功能添加
• 一个错误修复
• 一次重构
• 一次文档更新

这使得 Git 历史可导航且有意义。

故事弧线

您的提交应读起来像一个故事：

1. 设置: 初始项目结构、依赖项
2. 开发: 渐进式功能添加
3. 优化: 错误修复、性能优化
4. 完善: 文档、清理

最佳实践

应该提交当

✅ 您完成了一个逻辑工作单元（即使很小） ✅ 测试通过了所做的更改 ✅ 您即将切换任务或休息 ✅ 您重构了代码使其更清晰 ✅ 您修复了一个错误（每个错误一个提交） ✅ 您添加了新文件或模块 ✅ 您更新了文档 ✅ 您处于稳定检查点

不应该提交当

❌ 代码不编译或有语法错误 ❌ 测试失败（除非记录已知问题） ❌ 您有无关更改混在一起 ❌ 您有调试代码或临时注释 ❌ 您有秘密或敏感数据

提交消息模式

好的提交消息

功能: 添加 JWT 用户认证

实现基于 JWT 的认证系统，包括：
- 登录端点
- 令牌生成
- 令牌验证中间件

🤖 由 [Claude Code](https://claude.com/claude-code) 生成

共同作者: Claude <noreply@anthropic.com>

修复: 解决 WebSocket 处理程序中的内存泄漏

正确关闭 WebSocket 连接当客户端断开时
以防止内存累积。

🤖 由 [Claude Code](https://claude.com/claude-code) 生成

共同作者: Claude <noreply@anthropic.com>

重构: 将验证逻辑提取到单独模块

将验证函数从控制器移动到 validators/
以提高可重用性和测试性。

🤖 由 [Claude Code](https://claude.com/claude-code) 生成

共同作者: Claude <noreply@anthropic.com>

提交前缀

• 功能: - 新功能
• 修复: - 错误修复
• 重构: - 代码重构，无行为更改
• 测试: - 添加或更新测试
• 文档: - 文档更改
• 样式: - 格式化、空白更改
• 性能: - 性能改进
• 杂项: - 维护任务

示例

示例 1: 构建 REST API

好的故事化提交：

# 1. 设置
git commit -m "功能: 初始化 Express 服务器并配置"

# 2. 基础
git commit -m "功能: 添加与 Prisma 的数据库连接"

# 3. 功能开发
git commit -m "功能: 创建用户模型和迁移"
git commit -m "功能: 添加用户注册端点"
git commit -m "功能: 添加用户登录端点"
git commit -m "测试: 添加用户认证测试"

# 4. 优化
git commit -m "修复: 验证注册中的电子邮件格式"
git commit -m "重构: 将密码哈希提取到工具"

# 5. 文档
git commit -m "文档: 添加 API 端点文档"

示例 2: 错误修复过程

# 1. 识别和复现
git commit -m "测试: 添加分页边缘情况的失败测试"

# 2. 修复问题
git commit -m "修复: 处理分页中的空结果"

# 3. 验证
git commit -m "测试: 验证分页在边缘情况下工作"

# 4. 清理
git commit -m "重构: 简化分页逻辑"

示例 3: 重构

# 1. 准备
git commit -m "测试: 在重构前添加全面测试"

# 2. 小步骤
git commit -m "重构: 提取公共验证逻辑"
git commit -m "重构: 重命名混淆变量名"
git commit -m "重构: 将大函数拆分为小单元"

# 3. 验证
git commit -m "测试: 验证重构后所有测试仍通过"

常见模式

开发功能

1. 提交初始结构/骨架
2. 提交每个组件或模块
3. 提交编写时的测试
4. 发现错误时立即提交修复
5. 完成时提交文档
6. 集成最终提交

调试

1. 提交复现测试用例
2. 提交修复
3. 提交发现的任何相关改进
4. 提交问题文档

代码审查反馈

1. 单独提交每个建议更改
2. 使用描述性消息引用反馈
3. 保持提交小以便于审查

反模式

避免这些提交风格

❌ 垃圾车提交

git commit -m "更新了文件"  # 太模糊，更改太多

❌ 小说提交

git commit -m "修复错误并添加功能并更新文档并重构代码并..."

❌ WIP 垃圾邮件

git commit -m "wip"
git commit -m "wip2"
git commit -m "wip3"
# 即使是进行中工作，也使用更好的描述

❌ 时光机提交

# 做 50 个提交，然后将它们全部压缩成一个
# 这完全破坏了开发故事

✅ 更好方法: 在推送前本地清理无意义的提交，但保留逻辑故事：

# 保留讲述故事的逻辑提交
git rebase -i origin/main

# 结果: 干净的具有意义的提交故事
# 功能: 实现用户认证
# 测试: 添加认证测试
# 修复: 处理边缘情况
# 文档: 文档化认证 API

工作流集成

与功能分支

# 在功能分支上
git checkout -b feature/user-auth

# 做小提交
git commit -m "功能: 添加用户模型"
git commit -m "功能: 添加认证中间件"
git commit -m "测试: 添加认证测试"

# 合并时保留干净历史
git checkout main
git merge feature/user-auth

与拉取请求

小提交使代码审查更容易：

• 审查者可以逐步理解更改
• 讨论可以在特定提交上进行
• 更改更易于单独测试

与 CI/CD

频繁提交更频繁地触发 CI：

• 更早捕捉问题
• 较小的更改集更易于调试
• 更快的反馈循环

清理本地提交

黄金规则: 本地 vs 已推送

✅ 安全变基: 本地提交（尚未推送）

• 您可以自由重写、重新排序、压缩或编辑本地提交
• 交互式变基是清理混乱历史的朋友
• 其他人尚未基于这些提交工作

❌ 危险变基: 已推送提交（已在远程）

• 重写已推送提交会为协作者创建冲突
• 仅当您是分支上唯一人员时才变基已推送提交
• 需要强制推送，可能会丢失他人工作
• 例外: 个人功能分支，您是唯一贡献者

何时清理本地提交

在推送工作前，考虑清理如果您有：

• WIP 提交: 多个“进行中工作”或“wip”提交
• 修复提交: “哎呀，修复拼写错误”或“忘记添加文件”提交
• 调试提交: 添加然后删除调试代码的提交
• 逻辑分组: 相关更改分散在多个提交中
• 提交消息错误: 提交历史中的拼写错误或不清楚消息

用于清理的交互式变基

使用 git rebase -i 在推送前清理本地提交历史：

# 检查尚未推送的提交
git log origin/main..HEAD --oneline

# 交互式变基最后 5 个提交
git rebase -i HEAD~5

# 或变基从 main 分支以来的所有提交
git rebase -i origin/main

变基命令

在交互式变基编辑器中，您可以：

• pick - 保持提交不变
• reword - 保持提交但编辑消息
• edit - 暂停以修改提交
• squash - 合并到前一个提交，保留两个消息
• fixup - 合并到前一个提交，丢弃此消息
• drop - 完全移除提交
• reorder - 移动行以重新排序提交

常见清理模式

模式 1: 压缩修复提交

之前：

功能: 添加用户认证
wip: 添加测试
修复: 哎呀，忘记导入
修复: 测试中的拼写错误
测试: 添加更多边缘情况

变基后：

功能: 添加用户认证
测试: 添加认证测试

变基编辑器中的命令：

pick abc123 功能: 添加用户认证
pick def456 wip: 添加测试
fixup ghi789 修复: 哎呀，忘记导入
fixup jkl012 修复: 测试中的拼写错误
squash mno345 测试: 添加更多边缘情况

模式 2: 将 WIP 拆分为逻辑提交

之前：

wip: 东西
wip: 更多东西
wip: 最终更改

变基后：

功能: 实现用户认证
测试: 添加认证测试
文档: 文档化认证 API

变基编辑器中的命令：

edit abc123 wip: 东西
edit def456 wip: 更多东西
edit ghi789 wip: 最终更改

然后为每个提交：

git reset HEAD^           # 取消暂存提交
git add -p                # 选择性暂存更改
git commit -m "功能: 实现用户认证"
git add -p                # 暂存更多更改
git commit -m "测试: 添加认证测试"
# ... 等等
git rebase --continue

模式 3: 改进提交消息

之前：

东西
更多更改
最终

变基后：

功能: 添加 JWT 认证
测试: 添加认证测试
文档: 更新 API 文档

变基编辑器中的命令：

reword abc123 东西
reword def456 更多更改
reword ghi789 最终

示例工作流: 频繁提交，推送前清理

# 开发期间 - 频繁提交
git commit -m "wip: 开始认证实现"
git commit -m "wip: 添加 JWT 生成"
git commit -m "哎呀: 修复导入"
git commit -m "wip: 添加测试"
git commit -m "修复: 测试拼写错误"
git commit -m "wip: 添加验证"

# 推送前 - 检查已有内容
git log origin/main..HEAD --oneline
# 显示 6 个混乱的 WIP 提交

# 用交互式变基清理
git rebase -i origin/main

# 在编辑器中，整合为逻辑提交:
# - 压缩“哎呀”和“修复”提交
# - 合并相关的 WIP 提交
# - 重新措辞提交消息使其描述性

# 结果: 干净、逻辑的历史
git log origin/main..HEAD --oneline
#
# 功能: 实现 JWT 认证
# 测试: 添加认证测试
# 功能: 添加请求验证

# 现在推送干净历史
git push origin feature/user-auth

何时不要变基

不要变基如果：

• ❌ 提交已推送到共享分支（main, develop）
• ❌ 其他人已从您的提交分支
• ❌ 您正在结对编程，都推送到同一分支
• ❌ 提交是已合并拉取请求的一部分
• ❌ 您不确定影响（当有疑问时，不要变基）

从变基错误中恢复

如果变基出错：

# 中止进行中的变基
git rebase --abort

# 或使用 reflog 恢复（变基已完成）
git reflog                    # 找到变基前的提交
git reset --hard HEAD@{5}     # 返回该状态

最佳实践

1. 开发期间频繁提交 - 不担心完美的提交
2. 推送前审查 - 使用 git log 查看即将推送的内容
3. 推送前清理 - 使用交互式变基创建逻辑故事
4. 永远不变基已推送提交 - 除非您确定您是唯一的人
5. 使用描述性提交消息 - 即使在清理后，消息应清晰
6. 变基后测试 - 确保重写历史后测试仍通过

相关技能

• git-history-navigation: 理解 git log、bisect 和 blame
• git-branch-strategy: 有效管理分支
• code-review: 提交策略如何改进审查

成功提示

1. 上下文切换前提交 - 总是在更改任务前提交
2. 提交前审查 - 使用 git diff 审查更改
3. 为未来的您写提交消息 - 解释“为什么”不仅仅是“什么”
4. 保持故事连贯 - 每个提交应自己有意义
5. 使用钩子 - 让 git-storytelling 钩子提醒您提交
6. 推送前清理 - 使用 git rebase -i 在共享前打磨本地提交
7. 永远不变基已推送提交 - 尊重共享历史，仅变基本地工作

检查您的提交故事

审查您的提交以确保它们讲述一个好故事：

# 查看提交历史
git log --oneline --graph

# 查看每个提交中的更改
git log -p

# 审查最近提交
git log --oneline -10

一个好故事应：

• 易于遵循
• 逻辑有序
• 自文档化
• 有助于调试