git-commit

Git Conventional Commits

Overview

Create standardized, semantic git commits using the Conventional Commits specification. Analyze the actual diff to determine the appropriate type, scope, and message.

Language Settings

By default, generate Chinese commit messages. Users can specify another language via a parameter, for example:

• No parameter → Chinese message
• --lang=en → English message

Conventional Commits Format

<type>[可选 scope]: <描述>

[可选正文]

[optional footer]

### 中文消息示例

feat(auth): introduce JWT verification to secure the API

Implement JWT Token verification middleware to address the security risk of unauthenticated APIs:

• Verify the Token signature and expiration time to prevent forged requests
• Extract user claims from the Payload for downstream use
• Inject the user context into the request object to avoid repeated queries
• Handle Refresh Token rotation to maintain session continuity

### 英文消息示例

feat(auth): add JWT validation to secure API endpoints

## 提交类型

| 类型       | 用途                         |
| ---------- | ---------------------------- |
| `feat`     | 新功能                       |
| `fix`      | 修复缺陷                     |
| `docs`     | 仅文档变更                   |
| `style`    | 代码格式/风格（不影响逻辑）  |
| `refactor` | 重构（非功能/非修复）        |
| `perf`     | 性能优化                     |
| `test`     | 新增/更新测试                |
| `build`    | 构建系统/依赖变更            |
| `ci`       | CI/配置变更                  |
| `chore`    | 维护/杂项                    |
| `revert`   | 回退提交                     |

## 破坏性变更

Add an exclamation mark after type/scope

feat!: remove deprecated APIs to simplify API maintenance

BREAKING CHANGE footer

feat: support configuration inheritance to reduce duplicate configuration

BREAKING CHANGE: extends The behavior of the key has changed

## 提交拆分策略

当检测到以下情况时，应建议拆分为多个提交：

1. **混合类型**：新功能 + 缺陷修复在同一提交中
2. **多关注点**：不相关的变更混在一起
3. **大范围变更**：跨越多个模块的修改
4. **文件模式混合**：源码 + 测试 + 文档混杂
5. **依赖混杂**：依赖更新与功能代码混合

命中任一条时，**在动手之前**给出拆分方案（分几个提交、各是什么 type），再按用户的
选择走。什么时候做这件事，见「工作流程」第 2 步。

> 这条有实测依据：模型能正确识别出「新接口 + bug 修复」，却因为用户说了「一起提交」
> 就把建议咽了回去，直接合成 `feat(...)` —— **识别出来 ≠ 说出口**。原先流程里写的是
> 「暂存区有内容 → **直接**生成提交消息」，那个「直接」正好跳过了这个判断。

## 工作流程

### 1. 分析差异

```bash
# 首先检查暂存区
git diff --staged

# 同时检查状态，判断暂存区和工作区情况
git status --porcelain

By default, only commit staged code. The process is as follows:

1. First check whether the staging area has content (git diff --staged whether there is output)
2. The staging area has content → First go through the "Commit Splitting Strategy": if any of them matches (especially "mixed types"), first give splitting suggestions, then proceed according to your choice.Even if you say "commit them together", still suggest first — you may not realize the changes are mixed, or you may indeed want to merge them, and that is up to you. If confirmed not mixed → use the staged diff to generate the commit message
3. The staging area has no content → Prompt the user: "There are no files in the staging area. Do you want to commit the changes in the working tree?" — wait for the user to confirm before executing

2. Stage files (if needed)

Only stage after the user confirms committing working tree changes, or when logical grouping is needed:

# 暂存指定文件
git add path/to/file1 path/to/file2

# 按模式暂存
git add *.test.*
git add src/components/*

Never commit secret files(.env, credentials.json, private keys, etc.).

This ruleis not relaxed for any reason. None of the following three excuses hold:

• "It only contains placeholder values / is for testing" — whether it should go into version control is determined bythe nature of the file, not by its content; andonce it has been committed, even if it is deleted later, it is still in the history
• "The user explicitly requested it" — the user is not obligated to know which files must not be committed; that is exactly the point of this skill. You should refuse and explain the reason, rather than comply
• "Just this once" — history is permanent; there is no "this once"

The correct approach: add the file to .gitignore, commit only the remaining changes, andclearly tell the user why you refuse, as well as what to do if they really need it (inject via environment variables, or commit a .env.example）。

This has empirical basis: the model reads .env then judges on its own that "the content looks like a placeholder value," sosubmits it as the user requested. Once the criterion shifts from "the nature of the file" to "whether the content looks real," the rule becomes ineffective.

3. Generate the commit message

Analyze the diff to determine:

• Type: What type of change is this?
• Scope: Which area/module is affected?
• Description: A one-line summarywhy this change is being made(present tense, imperative mood, <72 characters), focusing on the motivation rather than the action itself

The description should explain "why," not just "what was changed." A good description lets readers understand the intent and context of the change without needing to look at the diff.

Example comparison:

# 不好 — 只说了做了什么
fix: 修改登录接口返回值

# 好 — 说明了为什么改
fix: 登录接口需返回用户角色以支持权限控制

# 不好 — 只说了做了什么
feat: 添加缓存模块

# 好 — 说明了为什么加
feat: 引入缓存层以降低数据库查询延迟

4. Execute the commit

# 单行
git commit -m "<type>[scope]: <描述>"

# 多行，含正文/脚注
git commit -m "$(cat <<'EOF'
<type>[scope]: <描述>

<可选正文>

<可选脚注>
EOF
)"

5. Push rules

By default, do not execute git push。 Only when the user explicitly says "push" should the push be executed after committing.

Best practices

• One commit contains only one logical change
• Use the present tense: "add" rather than "added"
• Use the imperative mood: "fix bug" rather than "fixed bug"
• Reference issues:Closes #123、Refs #456
• Keep the description within 72 characters

Git safety protocol

• Do not modify git config
• Do not execute destructive commands (--force, hard reset) without the user's explicit request
• Do not skip hooks (--no-verify) without the user's request
• Do not force push to main/master
• If a commit fails due to hooks, fix the issue and create a new commit (do not amend)