back
loading skill details...
Generate precise git commit messages following Conventional Commits with auto language detection, scope inference, and multi-module support.
---
name: git-commit
description: Generate git commit messages following Conventional Commits specification. Use this skill when users ask to: (1) Create a git commit with a meaningful message, (2) Generate commit messages from git changes, (3) Help write commit messages following best practices, (4) Format or improve existing commit messages. The skill supports both automatic analysis (by examining git diff) and interactive guided generation. Automatically detects project language style (Chinese/English) and adapts commit messages accordingly.
---
# Git Commit Message Generator
Generate conventional commit messages with automatic language style detection.
## Commit Format
```
<type>[optional scope]: <subject>
<body>
[optional footer]
```
**Types**: `feat` `fix` `docs` `style` `refactor` `perf` `test` `build` `ci` `chore` `revert`
**Rules**:
- Type: lowercase English, always
- Subject: <72 chars, imperative mood, no period
- Body: detailed explanation of changed files, core changes, problems solved, or behavior changes
- Footer: `Refs #123`, `BREAKING CHANGE: ...`, etc. Omit if not applicable.
## Output Behavior
**Default (full template)**: Always provide a complete commit command with type, scope, subject, body, and footer. This is the standard behavior unless the user requests otherwise.
```bash
git commit -m "$(cat <<'EOF'
<type>(<scope>): <subject>
<body>
<footer>
EOF
)"
```
**Short mode**: Only when the user explicitly says "简短一点", "只给 commit message", "只给命令", or similar brevity requests — output just the one-line subject:
```bash
git commit -m "<type>(<scope>): <subject>"
```
## Language Detection
Detect project language from multiple signals (in priority order):
1. **Recent commits** (primary): `git log -20 --oneline`
- Contains Chinese characters → Chinese
2. **README.md**: Check if README is written in Chinese
3. **Default**: Chinese
| Style | Format Example |
|-------|---------------|
| English | `feat(api): add user authentication endpoint` |
| Chinese | `feat(用户管理): 添加登录功能` |
**Language Rules**:
- **Type**: Always English (`feat`, `fix`, `refactor`, etc.)
- **Scope**: Follow project style (English or Chinese)
- **Subject/Body**: Match detected project language
## Workflow
### 1. Parallel Analysis (single response)
Run these in parallel to gather context:
```bash
git status
git diff --staged # staged changes (primary)
git diff # unstaged changes (fallback if nothing staged)
git log -20 --oneline # recent commits for language + style detection
```
If nothing is staged and nothing is unstaged, check:
```bash
git diff HEAD~1 # show last commit changes
```
### 2. Project Convention Detection
Before generating, check if the project has commit conventions:
1. Look for `.github/COMMIT_CONVENTION.md`, `CONTRIBUTING.md`, or similar
2. Check recent commit patterns for project-specific types or scopes
3. If project uses a convention (e.g., Angular, custom types), follow it **first**
### 3. Smart Type Inference
**Priority: project convention > keyword matching > file pattern matching**
| Pattern | Type |
|---------|------|
| `*.test.*`, `*.spec.*`, `__tests__/`, `*Test.java` | `test` |
| `package.json`, `*.lock`, `Dockerfile`, `Makefile`, `pom.xml`, `build.gradle` | `build` |
| `.github/`, `.gitlab-ci.yml`, `Jenkinsfile`, `*.yml` (CI config) | `ci` |
| `*.md`, `docs/`, `README*`, `CHANGELOG*` | `docs` |
| Only whitespace/formatting changes | `style` |
| Keywords: fix/bug/resolve/repair/patch | `fix` |
| Keywords: add/implement/create/introduce/support | `feat` |
| Keywords: refactor/extract/reorganize/restructure | `refactor` |
| Keywords: optimize/cache/performance/speed | `perf` |
| Keywords: update/upgrade/bump (dependencies) | `chore` |
| Keywords: revert/undo | `revert` |
| Mixed or unclear | `chore` |
### 4. Scope Inference
Extract scope from changed file paths:
**Strategy**: Use the most meaningful directory name under `src/` or project root.
| Path Pattern | Scope |
|-------------|-------|
| `src/api/user/*`, `server/api/*` | `api` or `user` |
| `src/components/Button/*` | `Button` or `components` |
| `src/views/目标管理/*` | `目标管理` |
| `src/utils/*`, `src/lib/*` | `utils` |
| Root config files only | omit scope |
| Mixed across many modules | omit scope or use broad scope |
**Rules**:
- Prefer the module name that best represents the change's impact
- If changes span multiple unrelated modules, omit scope
- If a single file is changed, use the parent directory name
- For monorepos: use package name as scope
### 5. Body Construction
The body must answer **what changed and why**, not how. Structure:
- **Multiple files**: Use numbered list (`1. 2. 3.`), each item specifies the file/module and the change
- **Single file**: One concise paragraph explaining the change
- **Bug fix**: Describe the problem, root cause, and solution
- **New feature**: Describe what it does and the use case
### 6. Breaking Changes
When changes break backward compatibility:
- Add `!` after type/scope: `feat(api)!: change response format`
- Add footer: `BREAKING CHANGE: <description of what breaks and migration path>`
### 7. Present & Confirm
Show the generated commit command and await user approval before executing.
## Examples
### Full Template — Chinese (default)
```bash
git commit -m "$(cat <<'EOF'
feat(用户管理): 添加登录功能
1. AuthService 实现基于JWT的用户认证，支持登录和登出。
2. TokenManager 添加令牌刷新机制和会话管理。
3. routes/auth.ts 更新API路由增加认证中间件。
关联 #123
EOF
)"
```
### Full Template — English
```bash
git commit -m "$(cat <<'EOF'
feat(api): add user authentication endpoint
1. Implement JWT-based authentication in AuthService for login/logout.
2. Add token refresh mechanism and session management in TokenManager.
3. Update routes/auth.ts with authentication middleware.
Closes #123
EOF
)"
```
### Bug Fix — Chinese
```bash
git commit -m "$(cat <<'EOF'
fix(支付模块): 修复订单金额计算错误
问题：当商品包含折扣时，总价计算未考虑优惠券叠加，导致金额偏高。
修复：OrderService.calculateTotal() 中调整折扣优先级，先应用商品折扣再叠加优惠券。
新增：utils/discount.ts 添加折扣计算工具函数及对应单元测试。
Fixes #456
EOF
)"
```
### Breaking Change
```bash
git commit -m "$(cat <<'EOF'
feat(api)!: 更改用户接口响应格式
将用户列表接口的响应结构从数组改为分页对象，包含 data、total、page 字段。
前端分页组件需同步更新以适配新格式。
BREAKING CHANGE: GET /api/users 响应格式从 User[] 变为 { data: User[], total: number, page: number }，所有消费该接口的客户端需更新解析逻辑。
EOF
)"
```
### Revert
```bash
git commit -m "$(cat <<'EOF'
revert: 回退用户头像上传功能
回退 commit abc1234 中引入的头像上传功能，原因是文件存储服务迁移中，
待迁移完成后重新引入。
Refs #789
EOF
)"
```
### Short Mode (only when user explicitly requests)
```bash
git commit -m "feat(api): add user authentication endpoint"
```
## Git Safety
- NEVER use `--no-verify` unless explicitly requested
- NEVER amend commits unless explicitly requested — create NEW commits
- NEVER force push without explicit request
- ALWAYS use HEREDOC for commit messages to preserve formatting
- Prefer `git add <specific-files>` over `git add .` — avoid accidentally staging sensitive files
- Warn user if staged files include `.env`, credentials, or large binaries
don't have the plugin yet? install it then click "run inline in claude" again.