Analyze the current git diff and automatically generate a commit message that conforms to the Conventional Commits specification, and intelligently detect the scope.
Quick Start
# 分析未暂存的改动,生成 commit message
python3 scripts/analyze_diff.py
# 分析已暂存(staged)的改动
python3 scripts/analyze_diff.py --staged
# 指定仓库路径
python3 scripts/analyze_diff.py --repo /path/to/repo
# JSON 格式输出(便于程序集成)
python3 scripts/analyze_diff.py --staged --format json
Manually override type or scope
python3 scripts/analyze_diff.py --staged --type-override feat --scope-override auth
## 使用流程(SOP)
### 1. 获取 diff 分析结果
在用户的 git 仓库中运行脚本,获取自动分析结果:
```bash
python3 scripts/analyze_diff.py --staged --format json
2. Review and adjust
The script will output:
- type: the automatically inferred commit type (feat / fix / docs / style / refactor / test / chore / perf / ci / build)
- scope: the scope detected from the file path (such as auth, api, ui, etc.)
- description: a brief description generated based on the change statistics
- commit_message: the assembled complete commit message
After reviewing the output, adjust it according to the actual semantics:
- If the type is inaccurate (for example, the script determines it as chore but it is actually feat), use
--type-overrideto override - If the scope is inappropriate, use
--scope-overrideto override - The description is recommended to be written manually based on the actual changes; the script output is for reference only
Note: type detection is based on file paths and change statistics. It is relatively accurate for detecting types such as test/docs/ci/build, but for cases where existing source code files are modified (feat vs fix vs refactor), you need to read the diff content and make a judgment.
3. Conventional Commits specification reference
<type>(<scope>): <description>
[optional body]
[optional footer(s)]
| Type | Meaning |
|---|---|
feat |
New feature |
fix |
Bug fix |
docs |
Documentation changes |
style |
Code formatting (does not affect logic) |
refactor |
Refactoring (does not involve new features or fixes) |
test |
Test-related |
chore |
Miscellaneous items such as build/tools/dependencies |
perf |
Performance optimization |
ci |
CI/CD configuration changes |
build |
Build system or external dependency changes |
4. Breaking Changes
If the changes include incompatible changes, add !:
feat(api)!: change authentication endpoint response format
Parameter description
| Parameter | Description | Default value |
|---|---|---|
--repo |
Git repository path | . |
--staged |
Analyze only staged changes | No |
--format |
Output format:text or json |
text |
--type-override |
Manually specify the commit type, skipping automatic detection | None |
--scope-override |
Manually specify the scope, skipping automatic detection | None |
Prerequisites
- Python 3.6+
- git is installed and in PATH
- The current directory or
--repopoints to a valid git repository