commit-helper

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Commit Helper

提交助手

Overview

概述

This skill helps create well-structured atomic commits by analyzing all code changes and intelligently splitting them into multiple logical commits. Each commit should be focused, related, and follow best practices.

此技能通过分析所有代码变更，智能将其拆分为多个逻辑提交，帮助创建结构清晰的原子提交。每个提交应聚焦于单一相关内容，并遵循最佳实践。

When to Use

使用场景

When users request "commit my changes", "commit code", or similar requests
When there are multiple unrelated changes in the working directory

当用户提出「提交我的变更」「提交代码」或类似请求时
当工作目录中存在多个不相关变更时

Workflow

工作流程

Execute the following steps in order:

按顺序执行以下步骤：

Step 1: Analyze Changes

步骤1：分析变更

Run
```
git status
```
to view all changed files
Run
```
git diff
```
to understand the nature of changes
Analyze changes to identify:
- Which files belong to the same module/directory
- Which files implement the same functionality
- What type of change each file represents (feat, fix, refactor, docs, etc.)
- Dependencies between files

运行
```
git status
```
查看所有已变更文件
运行
```
git diff
```
了解变更的具体内容
分析变更以确定：
- 哪些文件属于同一模块/目录
- 哪些文件实现了相同功能
- 每个文件的变更类型（feat、fix、refactor、docs等）
- 文件之间的依赖关系

Step 2: Group Changes

步骤2：分组变更

Split changes into multiple logical commits based on the following criteria:

Primary Grouping Criteria:

Functional cohesion: Files implementing the same functionality or solving the same problem are grouped together
Change type: Separate different types (feat, fix, refactor, docs, test, chore) into different commits when possible

Grouping Rules:

Each commit should represent one logical change
Related files (even in different directories) that implement one functionality should be in the same commit
Bug fixes should be separate from new features
Refactoring should be separate from feature additions
Test files should be grouped with the code they test
Documentation updates can be committed separately unless directly related to a specific feature

Grouping Examples:

Commit 1 (feat): User Authentication
  - src/auth/login.ts
  - src/auth/middleware.ts
  - src/routes/auth.ts
  - tests/auth.test.ts

Commit 2 (fix): Profile validation bug
  - src/user/profile.ts
  - tests/user.test.ts

Commit 3 (refactor): Error handling
  - src/utils/errors.ts
  - src/middleware/errorHandler.ts
  - Multiple files using the new error handling

根据以下标准将变更拆分为多个逻辑提交：

主要分组标准：

功能内聚性：实现同一功能或解决同一问题的文件归为一组
变更类型：尽可能将不同类型（feat、fix、refactor、docs、test、chore）的变更分到不同提交中

分组规则：

每个提交应代表一个逻辑变更
实现同一功能的相关文件（即使在不同目录）应放在同一个提交中
Bug修复应与新功能分开提交
重构应与功能新增分开提交
测试文件应与其测试的代码放在同一提交中
文档更新可单独提交，除非与特定功能直接相关

分组示例：

Commit 1 (feat): 用户认证功能
  - src/auth/login.ts
  - src/auth/middleware.ts
  - src/routes/auth.ts
  - tests/auth.test.ts

Commit 2 (fix): 资料验证修复
  - src/user/profile.ts
  - tests/user.test.ts

Commit 3 (refactor): 错误处理优化
  - src/utils/errors.ts
  - src/middleware/errorHandler.ts
  - 所有使用新错误处理逻辑的文件

Step 3: Generate Commit Messages

步骤3：生成提交信息

Generate commit messages following Conventional Commits specification for each commit group:

Format:

type(scope): brief description

Detailed explanation of why this change was made.
What problem was solved? What was the previous behavior?
How does this change improve the codebase?

Type Options:

```
feat
```
: New feature
```
fix
```
: Bug fix
```
refactor
```
: Refactoring code without changing functionality
```
docs
```
: Documentation changes
```
test
```
: Adding or updating tests
```
chore
```
: Maintenance tasks (dependencies, configs, etc.)
```
perf
```
: Performance improvements
```
style
```
: Code style/formatting changes
```
ci
```
: CI/CD changes

Scope Examples:

Module names:
```
auth
```
,
```
user
```
,
```
api
```
,
```
database
```
Component names:
```
LoginForm
```
,
```
ProfilePage
```
Domains:
```
validation
```
,
```
error-handling
```
,
```
logging
```

Message Guidelines:

Subject line (first line): Max 72 characters, use imperative mood ("add" not "added")
Body: Explain why, not what (the diff shows what)
Body should be 2-4 sentences providing context
Leave a blank line between subject and body

Example:

feat(auth): add JWT-based authentication system

Implemented complete authentication system using JWT tokens to replace
the previous session-based approach. This provides better scalability
for our API and supports stateless authentication across multiple servers.

为每个提交组生成遵循Conventional Commits规范的提交信息：

格式：

type(scope): 简要描述

详细说明变更的原因。
解决了什么问题？之前的行为是怎样的？
此变更如何改进代码库？

类型选项：

```
feat
```
: 新功能
```
fix
```
: Bug修复
```
refactor
```
: 不改变功能的代码重构
```
docs
```
: 文档变更
```
test
```
: 添加或更新测试
```
chore
```
: 维护任务（依赖、配置等）
```
perf
```
: 性能优化
```
style
```
: 代码风格/格式变更
```
ci
```
: CI/CD流程变更

范围示例：

模块名称：
```
auth
```
、
```
user
```
、
```
api
```
、
```
database
```
组件名称：
```
LoginForm
```
、
```
ProfilePage
```
领域：
```
validation
```
、
```
error-handling
```
、
```
logging
```

信息编写指南：

主题行（第一行）：最多72个字符，使用祈使语气（用"add"而非"added"）
正文：解释原因，而非内容（diff会展示内容）
正文应为2-4句，提供上下文信息
主题和正文之间留空行

示例：

feat(auth): 基于JWT的认证系统

使用JWT令牌实现完整的认证系统，替代之前的基于会话的方案。这为我们的API提供了更好的可扩展性，并支持多服务器间的无状态认证。

Step 4: Present Plan to User

步骤4：向用户展示提交方案

Display the proposed commit plan in this format:

🔍 Analyzed X files with changes

💡 Proposed commit plan:

【Commit 1/N】type(scope): description
  Files:
  ├─ path/to/file1.ts
  ├─ path/to/file2.ts
  └─ path/to/file3.ts

  Commit message:
  type(scope): brief description

  Detailed body explaining why...

【Commit 2/N】type(scope): description
  Files:
  ├─ path/to/file4.ts
  └─ path/to/file5.ts

  Commit message:
  type(scope): brief description

  Detailed body explaining why...

---
⚠️  Next: Code quality checks (linter + type checking)

Do you approve this commit plan? (yes/no/adjust)

Use the AskUserQuestion tool to wait for user confirmation before continuing.

按以下格式展示提议的提交方案：

🔍 已分析X个变更文件

💡 提议的提交方案：

【提交 1/N】type(scope): 描述
  文件：
  ├─ path/to/file1.ts
  ├─ path/to/file2.ts
  └─ path/to/file3.ts

  提交信息：
  type(scope): 简要描述

  详细说明变更原因...

【提交 2/N】type(scope): 描述
  文件：
  ├─ path/to/file4.ts
  └─ path/to/file5.ts

  提交信息：
  type(scope): 简要描述

  详细说明变更原因...

---
⚠️  下一步：代码质量检查（代码规范检查 + 类型检查）

是否批准此提交方案？（是/否/调整）

使用AskUserQuestion工具等待用户确认后再继续。

Step 5: Run Code Quality Checks

步骤5：运行代码质量检查

Before committing, run these checks:

Linter Check:
- Try to detect the project's linter (eslint, prettier, ruff, etc.)
- Run the appropriate lint command
- Common commands:
```
npm run lint
```
  ,
```
eslint .
```
  ,
```
prettier --check .
```
Type Check (if applicable):
- For TypeScript:
```
tsc --noEmit
```
  or
```
npm run type-check
```
- For Python:
```
mypy .
```
  or similar tools
- For other languages: appropriate type checkers

If checks fail:

Clearly display errors
Use AskUserQuestion to ask: "Code quality checks failed. Do you want to: 1) Fix issues and retry, 2) Commit anyway, 3) Cancel"
Respect the user's choice

If checks pass:

Notify user and proceed to commit

提交前，运行以下检查：

代码规范检查:
- 尝试检测项目使用的代码规范工具（eslint、prettier、ruff等）
- 运行对应的检查命令
- 常见命令：
```
npm run lint
```
  ,
```
eslint .
```
  ,
```
prettier --check .
```
类型检查（如适用）:
- TypeScript项目：
```
tsc --noEmit
```
  或
```
npm run type-check
```
- Python项目：
```
mypy .
```
  或类似工具
- 其他语言：使用对应的类型检查工具

若检查失败：

清晰展示错误信息
使用AskUserQuestion工具询问："代码质量检查失败。您希望：1) 修复问题后重试，2) 直接提交，3) 取消"
尊重用户的选择

若检查通过：

通知用户并继续提交流程

Step 6: Execute Commits

步骤6：执行提交

For each commit group in the plan:

Stage only the files for this commit:
bash
```
git add file1 file2 file3
```

Create commit with the generated message:

bash

git commit -m "$(cat <<'EOF'
type(scope): brief description

Detailed body explaining the change and its rationale.
Additional context if needed.
EOF
)"

Verify the commit was created successfully

Important Rules:

Execute commits sequentially, not in parallel
After each commit, confirm it succeeded before proceeding to the next
Do not automatically push to remote - only create local commits
Do not use
```
git add -A
```
or
```
git add .
```
- selectively stage files for each commit

对方案中的每个提交组执行以下操作：

仅暂存当前提交组的文件：
bash
```
git add file1 file2 file3
```

使用生成的信息创建提交：

bash

git commit -m "$(cat <<'EOF'
type(scope): 简要描述

详细说明变更内容及其理由。
如有需要可添加额外上下文。
EOF
)"

验证提交是否成功创建

重要规则：

按顺序执行提交，不要并行操作
每次提交后，确认成功再进行下一个
不要自动推送到远程仓库 - 仅创建本地提交
不要使用
```
git add -A
```
或
```
git add .
```
- 为每个提交选择性暂存文件

Step 7: Summary

步骤7：总结

After creating all commits, display a summary:

✅ Successfully created N commits:

1. abc1234 - feat(auth): add JWT authentication
2. def5678 - fix(user): fix profile validation
3. ghi9012 - refactor(api): improve error handling

All changes committed locally.
Use 'git push' to push to remote when ready.

创建所有提交后，展示总结信息：

✅ 成功创建N个提交：

1. abc1234 - feat(auth): 添加JWT认证
2. def5678 - fix(user): 修复资料验证
3. ghi9012 - refactor(api): 优化错误处理

所有变更已提交到本地仓库。
准备好后使用 'git push' 推送到远程仓库。

Important Notes

重要注意事项

Never auto-push: Always commit locally only, let users manually push
Atomic commits: Each commit should be independently buildable and testable
Clear messages: Focus on why in the commit body, not what
User control: Always show plan and get approval before executing
Quality first: Run checks before committing, but respect user's decision
Don't mix: Don't mix refactoring with features, or fixes with new features

禁止自动推送：始终仅创建本地提交，让用户手动推送
原子提交：每个提交应可独立构建和测试
清晰的信息：提交正文聚焦于原因，而非内容
用户控制权：执行前始终展示方案并获得批准
质量优先：提交前运行检查，但尊重用户的决定
避免混合：不要将重构与功能、修复与新功能混合提交

Example Session

示例会话

User: Please commit my code

Claude: 🔍 Analyzing code changes...

[Runs git status and git diff]

🔍 Analyzed 8 files with changes

💡 Proposed commit plan (3 commits):

【Commit 1/3】feat(auth): implement user login system
  Files:
  ├─ src/auth/login.ts (new file)
  ├─ src/auth/types.ts (modified)
  ├─ src/routes/auth.ts (new file)
  └─ tests/auth/login.test.ts (new file)

  Commit message:
  feat(auth): implement user login system

  Added JWT-based login functionality with email/password authentication.
  Includes token generation, validation middleware, and complete test coverage.

【Commit 2/3】fix(validation): correct email regex
  Files:
  ├─ src/utils/validation.ts (modified)
  └─ tests/utils/validation.test.ts (modified)

  Commit message:
  fix(validation): correct email regex

  Fixed email validation regex to properly handle plus signs and subdomains.
  The previous regex would reject valid emails like user+tag@subdomain.example.com.

【Commit 3/3】docs(readme): update installation instructions
  Files:
  └─ README.md (modified)

  Commit message:
  docs(readme): update installation instructions

  Updated setup guide to include new environment variables needed for
  authentication system. Added troubleshooting section for common JWT
  configuration issues.

---
⚠️  Next: Code quality checks (linter + type checking)

Do you approve this commit plan?

User: Yes

Claude: ✅ Plan approved. Running code quality checks...

[Runs npm run lint]
✅ Linter passed

[Runs npm run type-check]
✅ Type check passed

Creating commits...

✅ Commit 1/3: feat(auth) - abc1234
✅ Commit 2/3: fix(validation) - def5678
✅ Commit 3/3: docs(readme) - ghi9012

✅ Successfully created 3 commits:

1. abc1234 - feat(auth): implement user login system
2. def5678 - fix(validation): correct email regex
3. ghi9012 - docs(readme): update installation instructions

All changes committed locally.
Use 'git push' to push to remote when ready.

用户：请提交我的代码

Claude: 🔍 正在分析代码变更...

[运行git status和git diff]

🔍 已分析8个变更文件

💡 提议的提交方案（3个提交）：

【提交 1/3】feat(auth): 实现用户登录系统
  文件：
  ├─ src/auth/login.ts（新文件）
  ├─ src/auth/types.ts（已修改）
  ├─ src/routes/auth.ts（新文件）
  └─ tests/auth/login.test.ts（新文件）

  提交信息：
  feat(auth): 实现用户登录系统

  新增基于JWT的邮箱/密码登录功能，包括令牌生成、验证中间件和完整的测试覆盖。

【提交 2/3】fix(validation): 修正邮箱正则表达式
  文件：
  ├─ src/utils/validation.ts（已修改）
  └─ tests/utils/validation.test.ts（已修改）

  提交信息：
  fix(validation): 修正邮箱正则表达式

  修复邮箱验证正则表达式，使其正确处理加号和子域名。之前的正则表达式会拒绝类似user+tag@subdomain.example.com的有效邮箱。

【提交 3/3】docs(readme): 更新安装说明
  文件：
  └─ README.md（已修改）

  提交信息：
  docs(readme): 更新安装说明

  更新设置指南，添加认证系统所需的新环境变量。新增JWT配置常见问题的故障排除章节。

---
⚠️  下一步：代码质量检查（代码规范检查 + 类型检查）

是否批准此提交方案？

用户：是

Claude: ✅ 方案已批准。正在运行代码质量检查...

[运行npm run lint]
✅ 代码规范检查通过

[运行npm run type-check]
✅ 类型检查通过

正在创建提交...

✅ 提交 1/3: feat(auth) - abc1234
✅ 提交 2/3: fix(validation) - def5678
✅ 提交 3/3: docs(readme) - ghi9012

✅ 成功创建3个提交：

1. abc1234 - feat(auth): 实现用户登录系统
2. def5678 - fix(validation): 修正邮箱正则表达式
3. ghi9012 - docs(readme): 更新安装说明

所有变更已提交到本地仓库。
准备好后使用 'git push' 推送到远程仓库。

Advanced Scenarios

高级场景

Handling Large Change Sets

处理大型变更集

If more than 20 files changed:

Group more aggressively by top-level modules
Limit to maximum 5 commits for readability
Prioritize logical grouping over perfect atomicity

若变更文件超过20个：

按顶层模块更激进地分组
为了可读性，最多限制为5个提交
优先考虑逻辑分组而非完美的原子性

Mixed Changes in Single File

单个文件中的混合变更

If a single file has multiple unrelated changes:

Notify user that the file has mixed changes
Suggest using
```
git add -p
```
for partial staging if appropriate
Group the entire file with the most significant change

若单个文件包含多个不相关变更：

通知用户该文件存在混合变更
如合适，建议使用
```
git add -p
```
进行部分暂存
将整个文件与最主要的变更归为一组

Configuration Files

配置文件

For package.json, package-lock.json, poetry.lock, etc.:

Group with the commit that requires the dependency change
If it's a standalone dependency update, create a separate
```
chore(deps)
```
commit

对于package.json、package-lock.json、poetry.lock等：

与需要依赖变更的提交归为一组
若为独立的依赖更新，创建单独的
```
chore(deps)
```
提交

Generated Files

生成的文件

For build output, compiled files:

Warn user that these might not should be committed
Ask if they want to exclude them
Respect .gitignore patterns

对于构建输出、编译后的文件：

提醒用户这些文件可能不应被提交
询问用户是否要排除它们
遵循.gitignore规则

Error Handling

错误处理

No Changes Detected

未检测到变更

ℹ️  No changes detected in working directory.
Nothing to commit, working tree clean.

ℹ️  工作目录中未检测到变更。
没有可提交的内容，工作树干净。

All Files Already Staged

所有文件已暂存

ℹ️  All changes are already staged.
Do you want to continue with the current staging area, or reset and let
me reorganize commits? (continue/reorganize)

ℹ️  所有变更已暂存。
您希望继续使用当前暂存区，还是重置后让我重新组织提交？（继续/重新组织）

Commit Failed

提交失败

❌ Failed to create commit: [error message]

This might be due to:
- Pre-commit hook rejected the commit
- Invalid file permissions
- Git configuration issue

Please resolve the issue and try again.

❌ 提交创建失败：[错误信息]

可能的原因：
- 提交前钩子拒绝了提交
- 文件权限无效
- Git配置问题

请解决问题后重试。

Tips for Users

用户提示

Run this skill regularly to maintain clean commit history
The more detailed your code comments, the better the commit messages
Review the plan carefully - adjust grouping if needed
Keep working directory focused on related changes for best results

定期使用此技能以保持清晰的提交历史
代码注释越详细，生成的提交信息质量越高
仔细审查提交方案 - 如有需要可调整分组
为获得最佳效果，保持工作目录聚焦于相关变更