commit-message

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

commit-message

提交信息生成

Analyze git changes and generate context-aware commit messages following Conventional Commits.

分析Git变更，生成符合Conventional Commits规范的上下文感知型提交信息。

Quick Start

快速开始

bash

undefined

bash

undefined

Analyze all changes

分析所有变更

python3 .shared/commit-message/scripts/analyze_changes.py --analyze

Get batch commit suggestions

获取批量提交建议

python3 .shared/commit-message/scripts/analyze_changes.py --batch

Generate message for specific files

为指定文件生成提交信息

python3 .shared/commit-message/scripts/analyze_changes.py --generate "src/api/*.py"

undefined

python3 .shared/commit-message/scripts/analyze_changes.py --generate "src/api/*.py"

undefined

Commands

命令

Command	Description
`--analyze`	Show all changed files with status and categories
`--batch`	Suggest how to split changes into multiple commits
`--generate [pattern]`	Generate commit message for matching files
`--staged`	Only analyze staged changes (default: all changes)

命令	说明
`--analyze`	显示所有变更文件及其状态和分类
`--batch`	建议如何将变更拆分为多个提交
`--generate [pattern]`	为匹配的文件生成提交信息
`--staged`	仅分析已暂存的变更（默认：所有变更）

Commit Types

提交类型

Type	Description	Example
`feat`	New feature	`feat(api): add user authentication`
`fix`	Bug fix	`fix(db): resolve connection timeout`
`refactor`	Code restructuring	`refactor(utils): simplify helper functions`
`docs`	Documentation	`docs: update README`
`test`	Tests	`test(api): add user endpoint tests`
`chore`	Maintenance	`chore: update dependencies`
`style`	Formatting	`style: fix linting errors`

类型	说明	示例
`feat`	新功能	`feat(api): add user authentication`
`fix`	修复Bug	`fix(db): resolve connection timeout`
`refactor`	代码重构	`refactor(utils): simplify helper functions`
`docs`	文档更新	`docs: update README`
`test`	测试相关	`test(api): add user endpoint tests`
`chore`	维护工作	`chore: update dependencies`
`style`	代码格式调整	`style: fix linting errors`

Batch Commit Workflow

批量提交流程

When you have multiple unrelated changes:

Run
```
--batch
```
to see suggested commit groups
Stage files for first commit:
```
git add <files>
```
Commit with suggested message
Repeat for remaining groups

当你有多个不相关的变更时：

运行
```
--batch
```
查看建议的提交分组
暂存第一个提交的文件：
```
git add <files>
```
使用建议的信息提交
对剩余分组重复上述步骤

Grouping Strategy

分组策略

Files are grouped by:

Directory/Module:
```
src/api/
```
,
```
tests/
```
,
```
docs/
```
Change Type: Added vs Modified vs Deleted
Semantic Relationship: Related files together

文件将按照以下规则分组：

目录/模块：
```
src/api/
```
,
```
tests/
```
,
```
docs/
```
变更类型：新增、修改或删除
语义关联：将相关文件归为一组

Context-Aware Commit Messages

上下文感知型提交信息

Note: The
analyze_changes.py
script provides file grouping and basic suggestions. Use its output as a starting point, then read
git diff
to understand the actual changes and generate context-aware messages following the examples below.

When generating commit messages, analyze the actual code changes to infer business context. Don't just describe files—describe what the changes accomplish.

注意：
analyze_changes.py
脚本提供文件分组和基础建议。请将其输出作为起点，然后查看
git diff
以了解实际变更，并参照以下示例生成上下文感知型提交信息。

生成提交信息时，请分析实际代码变更以推断业务上下文。不要仅描述文件，要说明变更实现的功能。

Scope Guidelines

范围指南

The scope should reflect the business module or feature, not just the directory:

Scope Type	Example	When to Use
Feature/Module	`companion` , `calendar` , `inbox`	Changes to a specific product feature
Platform	`ios` , `android` , `web`	Platform-specific changes
Integration	`outlook` , `gmail` , `slack`	Third-party integration changes
Component	`auth` , `api` , `db`	Core infrastructure changes

范围应反映业务模块或功能，而不仅仅是目录：

范围类型	示例	使用场景
功能/模块	`companion` , `calendar` , `inbox`	针对特定产品功能的变更
平台	`ios` , `android` , `web`	特定平台的变更
集成	`outlook` , `gmail` , `slack`	第三方集成相关的变更
组件	`auth` , `api` , `db`	核心基础设施组件的变更

Input/Output Examples

输入/输出示例

Example 1: New Feature

Input (code changes):
  + src/companion/pages/AvailabilityDetailPage.tsx
  + src/companion/pages/AvailabilityActionsPage.tsx
  + src/companion/components/AvailabilityCard.tsx
  M src/companion/navigation/routes.ts

Output:
  feat(companion): add availability detail and actions pages for ios

  - New AvailabilityDetailPage showing time slot details
  - New AvailabilityActionsPage for booking/canceling
  - AvailabilityCard component for list display
  - Updated navigation routes

Example 2: Bug Fix

Input (code changes):
  M src/integrations/outlook/email_sender.py
  M src/integrations/outlook/auth.py

Output:
  fix(outlook): resolve email sending failures due to token expiration

  Refresh OAuth token before sending when close to expiry

Example 3: Multi-platform Change

Input (code changes):
  M ios/Calendar/CalendarView.swift
  M android/calendar/CalendarFragment.kt
  M web/src/calendar/Calendar.tsx

Output:
  feat(calendar): add week view across all platforms

  Implement consistent week view UI for iOS, Android, and web

Example 4: Chore/Maintenance

Input (code changes):
  M package.json
  M yarn.lock
  M requirements.txt

Output:
  chore(deps): update dependencies to latest versions

示例1：新功能

输入（代码变更）：
  + src/companion/pages/AvailabilityDetailPage.tsx
  + src/companion/pages/AvailabilityActionsPage.tsx
  + src/companion/components/AvailabilityCard.tsx
  M src/companion/navigation/routes.ts

输出：
  feat(companion): add availability detail and actions pages for ios

  - New AvailabilityDetailPage showing time slot details
  - New AvailabilityActionsPage for booking/canceling
  - AvailabilityCard component for list display
  - Updated navigation routes

示例2：Bug修复

输入（代码变更）：
  M src/integrations/outlook/email_sender.py
  M src/integrations/outlook/auth.py

输出：
  fix(outlook): resolve email sending failures due to token expiration

  Refresh OAuth token before sending when close to expiry

示例3：跨平台变更

输入（代码变更）：
  M ios/Calendar/CalendarView.swift
  M android/calendar/CalendarFragment.kt
  M web/src/calendar/Calendar.tsx

输出：
  feat(calendar): add week view across all platforms

  Implement consistent week view UI for iOS, Android, and web

示例4：维护工作

输入（代码变更）：
  M package.json
  M yarn.lock
  M requirements.txt

输出：
  chore(deps): update dependencies to latest versions

Writing Good Descriptions

撰写优质描述的技巧

Bad (Generic)	Good (Context-Aware)
`feat: add new file`	`feat(payments): add Stripe webhook handler`
`fix: fix bug`	`fix(auth): prevent session timeout on mobile`
`chore: update code`	`chore(ci): reduce build time with parallel jobs`
`refactor: refactor utils`	`refactor(api): extract rate limiting to middleware`

不佳（通用表述）	优秀（上下文感知）
`feat: add new file`	`feat(payments): add Stripe webhook handler`
`fix: fix bug`	`fix(auth): prevent session timeout on mobile`
`chore: update code`	`chore(ci): reduce build time with parallel jobs`
`refactor: refactor utils`	`refactor(api): extract rate limiting to middleware`

Key Principles

核心原则

Read the code - Understand what the changes actually do
Identify the feature - What user-facing or system capability is affected?
Be specific - Include relevant details (platform, integration, component)
Use active voice - "add", "fix", "update", not "added", "fixed", "updated"
Keep it concise - First line under 72 characters

阅读代码 - 理解变更的实际作用
识别功能 - 哪些用户可见或系统能力受到影响？
具体明确 - 包含相关细节（平台、集成、组件）
使用主动语态 - 使用“add”“fix”“update”而非“added”“fixed”“updated”
保持简洁 - 第一行不超过72个字符