Back to Details

git-commit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Git Commit

Git提交

Creates git commits following Conventional Commits format with proper type, scope, and subject.
创建遵循Conventional Commits格式的Git提交，包含正确的类型、作用域和主题。

Quick Start

快速开始

bash
undefined
bash
undefined

1. Check for project-specific commit conventions

1. 检查项目特定的提交约定

cat .claude/CLAUDE.md 2>/dev/null | grep -A 20 -i "commit"
cat .claude/CLAUDE.md 2>/dev/null | grep -A 20 -i "commit"

2. Stage changes

2. 暂存更改

git add <files> # or: git add -A
git add <files> # 或：git add -A

3. Create commit (branch commit format)

3. 创建提交（分支提交格式）

git commit -m "type(scope): subject
Body explaining HOW and WHY. Reference: Task X.Y, Req N"
undefined
git commit -m "type(scope): subject
解释更改的方式和原因。 参考：任务X.Y，需求N"
undefined

Commit Types

提交类型

Regular Branch Commits (During Development)

常规分支提交（开发阶段）

Format: 
type(scope): subject
TypePurpose
feat
New feature or functionality
fix
Bug fix or issue resolution
refactor
Code refactoring without behavior change
perf
Performance improvements
test
Test additions or modifications
ci
CI/CD configuration changes
docs
Documentation updates
chore
Maintenance, dependencies, tooling
style
Code formatting, linting (non-functional)
security
Security vulnerability fixes or hardening
格式：
type(scope): subject
类型用途
feat
新功能或功能特性
fix
Bug修复或问题解决
refactor
不改变行为的代码重构
perf
性能优化
test
测试用例新增或修改
ci
CI/CD配置变更
docs
文档更新
chore
维护工作、依赖更新、工具调整
style
代码格式化、语法检查（无功能变更）
security
安全漏洞修复或加固

Scope (Required, kebab-case)

作用域（必填，短横线命名）

Examples: 
validation
, 
auth
, 
cookie-service
, 
template
, 
config
, 
tests
, 
api
示例：
validation
, 
auth
, 
cookie-service
, 
template
, 
config
, 
tests
, 
api

Subject Line Rules

主题行规则

  • Max 50 characters after colon
  • Present tense imperative: add, implement, fix, improve, enhance, refactor, remove, prevent
  • NO period at the end
  • Specific and descriptive - state WHAT, not WHY
  • 冒号后的内容最多50个字符
  • 使用现在时祈使语气：add、implement、fix、improve、enhance、refactor、remove、prevent
  • 结尾不要加句号
  • 具体且有描述性 - 说明做了什么，而非为什么做

Core Workflow

核心工作流

1. Check Project Conventions

1. 检查项目约定

ALWAYS check first - project may override defaults:
bash
cat .claude/CLAUDE.md 2>/dev/null | grep -A 30 -i "commit"
cat .kiro/steering/*.md 2>/dev/null | grep -A 20 -i "commit"
If project specifies different format, USE PROJECT FORMAT.
务必先检查 - 项目可能会覆盖默认规则：
bash
cat .claude/CLAUDE.md 2>/dev/null | grep -A 30 -i "commit"
cat .kiro/steering/*.md 2>/dev/null | grep -A 20 -i "commit"
如果项目指定了不同的格式，使用项目格式。

2. Review Changes

2. 查看更改

bash
git status
git diff --staged  # if already staged
git diff           # if not staged
bash
git status
git diff --staged  # 已暂存的情况下
git diff           # 未暂存的情况下

3. Stage Files

3. 暂存文件

bash
git add <specific-files>  # preferred
bash
git add <特定文件>  # 推荐方式

or

或

git add -A # all changes

**NEVER commit**:
- `.env`, `credentials.json`, secrets
- `node_modules/`, `__pycache__/`, `.venv/`
- Large binary files without explicit approval
git add -A # 所有更改

**禁止提交**：
- `.env`, `credentials.json`, 密钥信息
- `node_modules/`, `__pycache__/`, `.venv/`
- 未获得明确批准的大型二进制文件

4. Create Commit

4. 创建提交

Simple change:
bash
git commit -m "fix(auth): use hmac.compare_digest for secure comparison"
Complex change (with body):
bash
git commit -m "$(cat <<'EOF'
feat(validation): add URLValidator with domain whitelist

Implement URLValidator class supporting:
- Domain whitelist enforcement (youtube.com, youtu.be)
- Dangerous scheme blocking (javascript, data, file)
- URL parsing with embedded credentials handling

Addresses Requirement 31: Input validation
Part of Task 5.1: Input Validation Utilities
EOF
)"
简单变更：
bash
git commit -m "fix(auth): 使用hmac.compare_digest进行安全比较"
复杂变更（带正文）：
bash
git commit -m "$(cat <<'EOF'
feat(validation): 添加带域名白名单的URLValidator

实现URLValidator类，支持：
- 域名白名单校验（youtube.com, youtu.be）
- 危险协议拦截（javascript, data, file）
- 包含嵌入式凭证的URL解析处理

对应需求31：输入校验
属于任务5.1：输入校验工具集
EOF
)"

5. Verify Commit

5. 验证提交

bash
git log -1 --format="%h %s"
git show --stat HEAD
bash
git log -1 --format="%h %s"
git show --stat HEAD

Body Format (Recommended for Complex Changes)

正文格式（复杂变更推荐使用）

<blank line>
Explain HOW and WHY the change was made.
- Use bullet points for multiple items
- Wrap at 72 characters

Reference: Task X.Y
Addresses: Req N
<空行>
解释更改的方式和原因。
- 多项内容使用项目符号
- 每行不超过72个字符

参考：任务X.Y
对应：需求N

Git Trailers

Git尾部信息

TrailerPurpose
Fixes #N
Links and closes issue on merge
Closes #N
Same as Fixes
Co-authored-by: Name <email>
Credit co-contributors
Place trailers at end of body after blank line. See 
references/commit_examples.md
for examples.
尾部信息用途
Fixes #N
关联并在合并时关闭议题
Closes #N
与Fixes作用相同
Co-authored-by: Name <email>
感谢共同贡献者
将尾部信息放在正文末尾的空行之后。示例可参考
references/commit_examples.md
。

Breaking Changes

破坏性变更

For incompatible API/behavior changes, use 
!
after scope OR 
BREAKING CHANGE:
footer:
feat(api)!: change response format to JSON:API

BREAKING CHANGE: Response envelope changed from `{ data }` to `{ data: { type, id, attributes } }`.
Triggers major version bump in semantic-release.
对于不兼容的API/行为变更，在作用域后添加
!
或使用
BREAKING CHANGE:
页脚：
feat(api)!: 将响应格式改为JSON:API

BREAKING CHANGE: 响应结构从`{ data }`改为`{ data: { type, id, attributes } }`。
会触发semantic-release中的主版本号升级。

Merge Commits (PR Closure)

合并提交（PR关闭）

For PRs, use extended description with sections:
bash
gh pr create --title "feat(security): implement input validation (Task 5)" --body "$(cat <<'EOF'
对于PR，使用包含章节的扩展描述：
bash
gh pr create --title "feat(security): 实现输入校验（任务5）" --body "$(cat <<'EOF'

Summary

摘要

  • Input validation utilities (URLValidator, FormatValidator)
  • Secure template processor with path traversal prevention
  • API key authentication middleware
  • 输入校验工具集（URLValidator、FormatValidator）
  • 防止路径遍历的安全模板处理器
  • API密钥认证中间件

Task Breakdown

任务分解

Task 5.1: Input Validation - URLValidator, FormatValidator Task 5.2: Template Processing - Path traversal prevention Task 5.3: API Key Auth - Multi-key support, excluded paths Task 5.4: Security Tests - 102 path traversal tests
任务5.1：输入校验 - URLValidator、FormatValidator 任务5.2：模板处理 - 路径遍历防护 任务5.3：API密钥认证 - 多密钥支持、排除路径 任务5.4：安全测试 - 102个路径遍历测试用例

Requirements Covered

覆盖的需求

Req 7, Req 9, Req 31, Req 33
需求7、需求9、需求31、需求33

Test Coverage

测试覆盖率

  • All 473 tests passing
  • Coverage: 93%
  • Pre-commit checks: passing EOF )"
undefined
  • 全部473个测试用例通过
  • 覆盖率：93%
  • 提交前检查：通过 EOF )"
undefined

Integration with Other Skills

与其他技能的集成

From github-pr-review

来自github-pr-review

When fixing review comments, use this format:
bash
git commit -m "fix(scope): address review comment #ID

Brief explanation of what was wrong and how it's fixed.
Addresses review comment #123456789."
修复评审意见时，使用以下格式：
bash
git commit -m "fix(scope): 处理评审意见#ID

简要说明问题所在及修复方式。
对应评审意见#123456789。"

From github-pr-creation

来自github-pr-creation

Before creating PR, ensure all commits follow this format. The PR skill will:
  1. Analyze commits for proper format
  2. Extract types for PR labels
  3. Build PR description from commit bodies
创建PR前，确保所有提交都遵循此格式。PR技能会：
  1. 分析提交是否符合正确格式
  2. 提取类型用于PR标签
  3. 从提交正文构建PR描述

Important Rules

重要规则

  • ALWAYS check project conventions (CLAUDE.md) before committing
  • ALWAYS use project format if it differs from default
  • ALWAYS include scope in parentheses
  • ALWAYS use present tense imperative verb
  • NEVER end subject with period
  • NEVER commit secrets or credentials
  • NEVER use generic messages ("update code", "fix bug", "changes")
  • NEVER exceed 50 chars in subject line
  • Group related changes -> single focused commit
  • 务必在提交前检查项目约定（CLAUDE.md）
  • 务必在项目格式与默认不同时使用项目格式
  • 务必在括号中包含作用域
  • 务必使用现在时祈使语气动词
  • 禁止主题行结尾加句号
  • 禁止提交密钥或凭证信息
  • 禁止使用通用消息（"update code"、"fix bug"、"changes"）
  • 禁止主题行超过50个字符
  • 相关变更分组 -> 单个聚焦的提交

Examples

示例

Good:
feat(validation): add URLValidator with domain whitelist
fix(auth): use hmac.compare_digest for secure key comparison
refactor(template): consolidate filename sanitization logic
test(security): add 102 path traversal prevention tests
Bad:
update validation code           # no type, no scope, vague
feat: add stuff                  # missing scope, too vague
fix(auth): fix bug               # circular, not specific
chore: make changes              # missing scope, vague
feat(security): improve things.  # has period, vague
正确示例：
feat(validation): 添加带域名白名单的URLValidator
fix(auth): 使用hmac.compare_digest进行安全密钥比较
refactor(template): 整合文件名清理逻辑
test(security): 添加102个路径遍历防护测试用例
错误示例：
update validation code           # 无类型、无作用域、模糊
feat: add stuff                  # 缺少作用域、过于模糊
fix(auth): fix bug               # 循环表述、不具体
chore: make changes              # 缺少作用域、模糊
feat(security): improve things.  # 有句号、模糊

References

参考

  • references/commit_examples.md
    - Extended examples by type
  • references/commit_examples.md
    - 按类型分类的扩展示例