commit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Commit

提交

Overview

概述

Create safe, structured commits with deterministic checks and consistent message quality. Run a guard before staging, then commit using Conventional Commits with a descriptive subject and required body bullets.

创建安全、结构化的提交，包含确定性检查和一致的信息质量。在暂存更改前先运行安全检查，然后使用Conventional Commits格式提交，包含描述性主题和必填的正文项目符号。

Workflow

工作流程

Run safety guard:
- ```
python3 scripts/precommit_guard.py
```
Abort immediately if the guard exits non-zero.
- Do not run
```
git add
```
  or
```
git commit
```
  when blocked.
Stage all changes only after guard passes:
- ```
git add . -A
```

Review staged changes:

```
git diff --cached --name-only
```
```
git diff --cached --stat
```

Compose commit subject and body using the format rules below.
Execute commit:
- ```
git commit -m "<subject>" -m "<body>"
```

运行安全检查：
- ```
python3 scripts/precommit_guard.py
```
若安全检查返回非零值则立即终止操作。
- 被阻止时不要执行
```
git add
```
  或
```
git commit
```
  命令。
仅在安全检查通过后暂存所有更改：
- ```
git add . -A
```

查看已暂存的更改：

```
git diff --cached --name-only
```
```
git diff --cached --stat
```

按照以下格式规则编写提交主题和正文。
执行提交：
- ```
git commit -m "<subject>" -m "<body>"
```

Safety Guard Rules

安全检查规则

Abort when any path matches one of these conditions:

Log-like files:

```
*.log
```
,
```
*.out
```
,
```
*.err
```

npm-debug.log*

yarn-debug.log*

yarn-error.log*

pnpm-debug.log*

any file under a
```
logs/
```
directory

Untracked high-risk binary extensions:

```
.exe
```
,
```
.dll
```
,
```
.so
```
,
```
.dylib
```
,
```
.bin
```
,
```
.class
```
```
.zip
```
,
```
.tar
```
,
```
.gz
```
,
```
.bz2
```
,
```
.xz
```
,
```
.7z
```
,
```
.rar
```
,
```
.jar
```
```
.iso
```
,
```
.dmg
```
,
```
.db
```
,
```
.sqlite
```
,
```
.sqlite3
```

If blocked, list offending files grouped by reason and request user action. Do not auto-delete files.

当任何文件路径符合以下任一条件时终止操作：

类日志文件：

```
*.log
```
,
```
*.out
```
,
```
*.err
```

npm-debug.log*

yarn-debug.log*

yarn-error.log*

pnpm-debug.log*

```
logs/
```
目录下的所有文件

未追踪的高风险二进制文件：

```
.exe
```
,
```
.dll
```
,
```
.so
```
,
```
.dylib
```
,
```
.bin
```
,
```
.class
```
```
.zip
```
,
```
.tar
```
,
```
.gz
```
,
```
.bz2
```
,
```
.xz
```
,
```
.7z
```
,
```
.rar
```
,
```
.jar
```
```
.iso
```
,
```
.dmg
```
,
```
.db
```
,
```
.sqlite
```
,
```
.sqlite3
```

若被阻止，按原因分组列出违规文件并请求用户操作。不要自动删除文件。

Commit Message Format

提交信息格式

Use Conventional Commits subject:

```
<type>(<scope>): <description>
```
Scope is optional, but prefer it when clear.
Subject must describe what changed (not only intent), be imperative, and avoid trailing period.
Keep subject concise (prefer <= 72 chars).

Allowed

type

values:

feat

fix

refactor

docs

test

chore

build

ci

perf

style

revert

Require commit body:

Provide bullet lines summarizing key changes and impact.
Mention migration/risk notes when relevant.
Use concise, factual bullets.

Example:

Subject:

fix(auth): handle token refresh race in session middleware

Body:

- Serialize refresh attempts per user session to prevent duplicate refresh calls.

- Add timeout handling so failed refresh does not block subsequent requests.

- Update session middleware tests for concurrent request scenarios.

使用Conventional Commits主题格式：

```
<type>(<scope>): <description>
```
Scope（范围）为可选字段，但在明确时建议填写。
主题必须描述具体更改内容（而非仅意图），使用祈使语气，且末尾不加句号。
主题需简洁（建议不超过72个字符）。

允许的

type

值：

feat

fix

refactor

docs

test

chore

build

ci

perf

style

revert

提交正文为必填项：

使用项目符号列表总结关键更改和影响。
相关时提及迁移/风险说明。
使用简洁、真实的项目符号。

示例：

主题：

fix(auth): handle token refresh race in session middleware

正文：

- Serialize refresh attempts per user session to prevent duplicate refresh calls.

- Add timeout handling so failed refresh does not block subsequent requests.

- Update session middleware tests for concurrent request scenarios.

Execution Notes

执行说明

Prefer one logical commit for the current request.
If changes are unrelated, split into separate commits and repeat the guard + staging flow for each.
If message quality is uncertain, summarize staged diff first, then derive subject/body.

针对当前请求优先创建一个逻辑独立的提交。
若更改内容不相关，拆分为多个独立提交，并为每个提交重复执行安全检查+暂存流程。
若对提交信息质量不确定，先总结已暂存的差异内容，再推导主题和正文。