git-commit-expert

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Expert Skill

1. Core Philosophy (The Brain)

1. 核心理念（思维框架）

"Think before you commit." Before executing any git command, you must adopt the mindset of a Senior Engineer. Your goal is not just to "save code," but to create a clean, reviewable, and safe project history.

"提交前先思考。" 在执行任何Git命令前，你必须以资深工程师的思维模式思考。你的目标不只是“保存代码”，而是创建清晰、可评审且安全的项目历史。

Decision Protocol

决策准则

Before acting, answer these questions:

Atomicity: "Do these changes represent ONE logical task?"
- If Mixed (e.g., formatting + logic): STOP. Plan to split using
```
git add -p
```
  .
- If Multiple Features: STOP. Split into separate commits.
Clarity: "Can I describe this change in a single 'Subject' line?"
- If No: The commit is too big or mixed. STOP and go back to the inspection/staging phase to split the work.
Safety: "Did I verify what I'm about to commit?"
- Check for secrets, debug logs, and unintended file deletions.

行动前，请先回答以下问题：

原子化：“这些变更是否代表一项独立的逻辑任务？”
- 若为混合变更（例如：格式化+逻辑修改）：停止操作。计划使用
```
git add -p
```
  拆分变更。
- 若包含多个功能：停止操作。拆分为多个独立提交。
清晰性：“我能否用一句话概述这项变更？”
- 若不能：说明提交内容过大或混杂。停止操作并回到检查/暂存阶段拆分工作。
安全性：“我是否已验证即将提交的内容？”
- 检查是否包含密钥、调试日志和意外删除的文件。

Interaction Strategy

交互策略

If instructions are vague, ASK the user:

"Should this be a single commit or split into logical parts?"
"Are there specific scope requirements for this project?"
"Would you like me to run tests/linting before committing?"

若用户指令模糊，主动询问用户：

“这应该作为单个提交还是拆分为多个逻辑部分？”
“该项目是否有特定的范围要求？”
“提交前是否需要我运行测试/代码检查？”

Language Protocol

语言规范

Standard:
```
type
```
and
```
scope
```
should generally remain in English (e.g.,
```
feat
```
,
```
fix
```
) to maintain tool compatibility.
Subject/Body:
- If the user prompts in English -> Use English.
- If the user prompts in another language (e.g., Chinese) -> ASK: "Shall I generate the commit message in English (standard) or keep it in Chinese?"
- Context Awareness: Check
```
git log
```
  briefly. If the history is predominantly in a specific language, default to that language.

标准要求：
```
type
```
和
```
scope
```
通常应保留英文（例如：
```
feat
```
、
```
fix
```
），以保持工具兼容性。
主题/正文：
- 若用户用英文提问 -> 使用英文。
- 若用户用其他语言（例如中文）提问 -> 询问：“我应该用英文（标准格式）生成提交信息，还是保留为中文？”
- 上下文感知：简要查看
```
git log
```
  。若历史提交信息主要使用某一语言，则默认使用该语言。

Sample Dialogues

对话示例

Mixed Changes: "I noticed you modified both the API logic and some CSS styling. To keep the history clean, should I split these into two separate commits: one for
```
fix(api)
```
and one for
```
style(ui)
```
?"
Vague Request: "You asked to 'save work', but the changes look like a complete feature. Shall I commit this as
```
feat(user): add profile page
```
?"

混合变更：“我注意到你同时修改了API逻辑和CSS样式。为保持历史清晰，是否需要将这些拆分为两个独立提交：一个
```
fix(api)
```
和一个
```
style(ui)
```
？”
模糊请求：“你要求‘保存工作’，但变更看起来像是一个完整功能。是否需要将其提交为
```
feat(user): add profile page
```
？”

2. Commit Standards (The Law)

2. 提交标准（执行准则）

Strictly adhere to the Conventional Commits specification.

严格遵循Conventional Commits规范。

Format

格式

text

<type>(<scope>): <subject>

<body>

<footer>

text

<type>(<scope>): <subject>

<body>

<footer>

Type Enumeration

类型枚举

Type	Semantic Meaning	SemVer
feat	A new feature	`MINOR`
fix	A bug fix	`PATCH`
docs	Documentation only	`PATCH`
style	Formatting (whitespace, semi-colons, etc.)	`PATCH`
refactor	Code change (no feature, no fix)	`PATCH`
perf	Performance improvement	`PATCH`
test	Adding or correcting tests	`PATCH`
build	Build system / dependencies	`PATCH`
ci	CI configuration / scripts	`PATCH`
chore	Maintainance (no src/test change)	`PATCH`
revert	Reverting a previous commit	`PATCH`

类型	语义	SemVer
feat	新增功能	`MINOR`
fix	修复Bug	`PATCH`
docs	仅修改文档	`PATCH`
style	格式调整（空格、分号等）	`PATCH`
refactor	代码重构（无新增功能、无Bug修复）	`PATCH`
perf	性能优化	`PATCH`
test	添加或修正测试	`PATCH`
build	构建系统/依赖项修改	`PATCH`
ci	CI配置/脚本修改	`PATCH`
chore	维护工作（无源码/测试文件修改）	`PATCH`
revert	回滚之前的提交	`PATCH`

Scope Inference

范围推断

Rule: Automatically infer the scope based on the file paths of staged changes.
Example:
```
src/auth/login.ts
```
-> scope:
```
auth
```
Example:
```
components/Button.tsx
```
-> scope:
```
ui
```
or
```
components
```
Example:
```
README.md
```
-> scope:
```
docs
```

规则：根据暂存文件的路径自动推断范围。
示例：
```
src/auth/login.ts
```
-> 范围：
```
auth
```
示例：
```
components/Button.tsx
```
-> 范围：
```
ui
```
或
```
components
```
示例：
```
README.md
```
-> 范围：
```
docs
```

Writing Rules

撰写规则

Subject: Imperative, present tense ("Add" not "Added"). No trailing period. Max 72 chars.
Body: Focus on WHY and WHAT, not HOW. Explain the motivation and contrast with previous behavior.

Breaking Changes:

Add
```
!
```
after type/scope:
```
feat(api)!: remove v1 endpoints
```
Add footer:
```
BREAKING CHANGE: <description>
```

主题：使用祈使句、现在时态（用“Add”而非“Added”）。结尾不加句号。最多72个字符。
正文：重点说明原因和内容，而非实现方式。解释变更动机，并对比之前的行为。

破坏性变更：

在类型/范围后添加
```
!
```
：
```
feat(api)!: remove v1 endpoints
```
添加页脚：
```
BREAKING CHANGE: <description>
```

3. Execution & Tooling (The Hands)

3. 执行与工具（操作指南）

Use this specific workflow to execute tasks safely.

使用以下特定工作流安全执行任务。

Step 0: Branch Check & Setup

步骤0：分支检查与设置

Check Current Branch:
```
git branch --show-current
```
Action: If on protected branches (
```
main
```
,
```
master
```
,
```
dev
```
):
- Create New Branch: Do not commit directly.
- Naming Convention:
```
<type>/<short-description>
```
- Example:
```
git checkout -b fix/login-error
```
  or
```
feat/dark-mode
```

检查当前分支：
```
git branch --show-current
```
操作：若当前处于受保护分支（
```
main
```
、
```
master
```
、
```
dev
```
）：
- 创建新分支：不要直接提交。
- 命名规范：
```
<type>/<short-description>
```
- 示例：
```
git checkout -b fix/login-error
```
  或
```
feat/dark-mode
```

Step 1: Inspection

步骤1：检查

bash

git status              # What's the state?
git diff                # Review unstaged changes
git diff --cached       # Review staged changes (Sanity Check)

bash

git status              # 当前状态？
git diff                # 查看未暂存的变更
git diff --cached       # 查看已暂存的变更（ sanity检查）

Step 2: Staging (The "Atomic" Step)

步骤2：暂存（“原子化”步骤）

Prefer
```
git add -p
```
(patch mode) to interactively choose hunks. This ensures you only stage what you intended.
Avoid
```
git add .
```
unless you have explicitly verified every file.

优先使用
```
git add -p
```
（补丁模式）交互式选择代码块。确保仅暂存预期的变更。
避免使用
```
git add .
```
，除非你已明确验证每一个文件。

Step 3: Verification (The "Zero-Failure" Check)

步骤3：验证（“零失败”检查）

Mandatory: Never commit code that hasn't been verified by the current project's toolchain. This prevents "broken-heart" commits and maintains a clean, buildable history.
Protocol:
- Build/Compile: If the project has a build step (Astro, Vite, Cargo, Go build, Java/C#, Mobile), run it to ensure no syntax errors or sync issues.
- Test/Check: Run the relevant unit tests (
```
npm test
```
  ,
```
pytest
```
  ,
```
cargo test
```
  ) or static analysis (
```
cargo check
```
  ,
```
tsc
```
  ).
- Lint: Run
```
npm run lint
```
  or equivalent to maintain style consistency.
Agent Logic: If you are unsure which command to run, scan
```
package.json
```
,
```
Makefile
```
,
```
README.md
```
, or ASK the user: "What is the standard command to verify the build/tests here?"

强制要求：绝不要提交未通过当前项目工具链验证的代码。这可以避免“问题提交”，并保持历史记录清晰、可构建。
执行规范：
- 构建/编译：若项目包含构建步骤（Astro、Vite、Cargo、Go build、Java/C#、移动端），执行构建以确保无语法错误或同步问题。
- 测试/检查：运行相关单元测试（
```
npm test
```
  、
```
pytest
```
  、
```
cargo test
```
  ）或静态分析（
```
cargo check
```
  、
```
tsc
```
  ）。
- 代码检查：运行
```
npm run lint
```
  或等效命令以保持风格一致。
Agent逻辑：若不确定应运行哪个命令，扫描
```
package.json
```
、
```
Makefile
```
、
```
README.md
```
，或询问用户：“此处验证构建/测试的标准命令是什么？”

Step 4: Commit

步骤4：提交

bash

git commit -m "<type>(<scope>): <subject>" -m "<body>"

bash

git commit -m "<type>(<scope>): <subject>" -m "<body>"

Step 5: Sync & Push (Optional but Recommended)

步骤5：同步与推送（可选但推荐）

Pre-Push Sync: Always advise
```
git pull --rebase
```
before pushing to keep history linear.
Push:
```
git push origin <current-branch>
```
Verification: Ensure the remote branch target is correct.

推送前同步：推送前建议始终执行
```
git pull --rebase
```
以保持历史记录线性。
推送：
```
git push origin <current-branch>
```
验证：确保远程分支目标正确。

Security & Safety Protocols (Non-negotiable)

安全保障协议（不可妥协）

NEVER commit secrets (API keys, .env, credentials).
NEVER update git config (user.name, user.email, core.editor, etc.).
NEVER use
```
--force
```
,
```
--hard
```
, or
```
--no-verify
```
unless explicitly ordered by the user.
NEVER force push to shared branches (
```
main
```
,
```
master
```
,
```
dev
```
).
ALWAYS verify the branch before committing.
ERROR HANDLING: If a commit fails due to hooks (lint/test), FIX the issue and retry the commit standardly. Do not blindly use
```
--no-verify
```
or complex amend logic without understanding the error.

绝不要提交密钥（API密钥、.env、凭证）。
绝不要修改Git配置（user.name、user.email、core.editor等）。
绝不要使用
```
--force
```
、
```
--hard
```
或
```
--no-verify
```
，除非用户明确要求。
绝不要强制推送到共享分支（
```
main
```
、
```
master
```
、
```
dev
```
）。
始终在提交前验证分支。
错误处理：若提交因钩子（lint/test）失败，修复问题后再按标准流程重试提交。不要在未理解错误原因的情况下盲目使用
```
--no-verify
```
或复杂的修改逻辑。

4. Examples

4. 示例

Simple Bug Fix

简单Bug修复

text

fix(api): handle null response in user endpoint

The user API could return null for deleted accounts, causing a crash
in the dashboard. Added a null check before accessing user properties.

text

fix(api): 处理用户接口的空响应

用户API在返回已删除账户信息时可能返回null，导致仪表盘崩溃。
在访问用户属性前添加了空值检查。

Feature with Scope

带范围的功能新增

text

feat(alerts): add Slack thread replies for alert updates

When an alert is updated or resolved, post a reply to the original
Slack thread instead of creating a new message. This keeps related
notifications grouped together.

text

feat(alerts): 为告警更新添加Slack线程回复

当告警更新或解决时，在原Slack线程中回复，而非创建新消息。
这样可将相关通知分组展示。

Refactor

代码重构

text

refactor: extract common validation logic to shared module

Move duplicate validation code from three endpoints into a shared
validator class. No behavior change.

text

refactor: 将通用验证逻辑提取到共享模块

将三个接口中的重复验证代码迁移到共享验证器类中。无行为变更。

Breaking Change

破坏性变更

text

feat(api)!: remove deprecated v1 endpoints

Remove all v1 API endpoints that were deprecated in version 23.1.
Clients should migrate to v2 endpoints.

BREAKING CHANGE: v1 endpoints no longer available.

text

feat(api)!: 移除已废弃的v1接口

移除所有在23.1版本中已废弃的v1 API接口。
客户端应迁移到v2接口。

BREAKING CHANGE: v1接口已不再可用。

Revert

回滚提交

text

revert: feat(api): add new endpoint

This reverts commit abc123def456.
Reason: Caused performance regression in production.

text

revert: feat(api): add new endpoint

此提交回滚了abc123def456提交。
原因：导致生产环境性能下降。