# Git Structured Commit

> Review working-tree changes and create focused Git commits with Chinese Conventional Commit messages using required type and subject plus optional scope. Use when Codex is asked to commit changes, initialize version control and commit a project, split a large change set into logical commits, prepare local commit history, or validate commit messages. Initialize Git when the intended project has no repository, stage only explicit functional groups, preserve unrelated changes, and never bundle the whole working tree by default.

- Skill: `songyw2003/git-structured-commit` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add songyw2003/git-structured-commit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/songyw2003/git-structured-commit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: songyw2003 (https://skillmd.com/u/songyw2003)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/songyw2003/git-structured-commit

---


# Structured Git Commit

Create small, coherent commits whose content, validation, and message describe one functional change. Preserve unrelated or ambiguous changes in the working tree.

## Commit message format

Use exactly:

```text
<type>(<scope>): <subject>
```

Omit the parentheses when scope is unnecessary:

```text
<type>: <subject>
```

Require `type` and `subject`. Keep `scope` optional and name the affected module, feature, or subsystem. Write `subject` in concise Chinese, preferably no longer than 50–72 characters. Describe the result rather than the editing action.

Use only these types:

| Type | Purpose | Example |
|---|---|---|
| `feat` | 新功能 | `feat(marker): 增加圆形标志点检测模块` |
| `fix` | 修复 bug | `fix(camera): 修复左相机图像未加载问题` |
| `docs` | 文档更新 | `docs: 补充项目安装与使用说明` |
| `style` | 代码格式修改，不影响功能 | `style: 调整缩进和空格` |
| `refactor` | 重构，不新增功能且不修复 bug | `refactor(reconstruction): 优化3D重建算法逻辑` |
| `perf` | 性能优化 | `perf(marker): 提升标志点匹配速度` |
| `test` | 增加或修改测试 | `test: 添加点云拟合单元测试` |
| `chore` | 构建、配置或工具变更 | `chore: 更新CMakeLists.txt` |
| `build` | 构建依赖和版本 | `build: 升级OpenCV到4.9.0` |
| `ci` | 持续集成配置 | `ci: 修改GitHub Actions工作流` |

Run `scripts/validate_commit_message.py '<message>'` before committing.

## Locate or initialize the repository

1. Determine the intended project root from the user's scope, current directory, manifests, and repository documentation.
2. Run `git rev-parse --show-toplevel`.
3. If no repository exists, run `git init` in the intended project root. Never initialize `$HOME` or another broad parent merely because it is the current directory.
4. Check `git config user.name` and `git config user.email`. Do not invent an identity or modify global Git configuration. Ask the user only if a commit is blocked by missing identity.
5. Read repository-level `AGENTS.md` and applicable contribution or commit instructions. Apply stricter repository rules when they do not conflict with the user's explicit format.

`git init` creates the repository but not a synthetic empty commit. Make the first commit a meaningful functional group.

## Inventory changes before staging

Run and inspect:

```bash
git status --short --branch
git diff --stat
git diff
git diff --cached
git ls-files --others --exclude-standard
```

Inspect untracked files before deciding whether they belong. Identify generated outputs, downloaded models, datasets, virtual environments, caches, credentials, `.env` files, private keys, large binaries, and unrelated user work. Do not stage them unless they are clearly intentional project artifacts within the request.

If changes were already staged, inspect them and preserve that staging intent unless the user authorizes regrouping. Do not assume every dirty file belongs to Codex's work.

## Plan functional commit groups

Group by independently understandable behavior, not merely by file extension or directory. A good group:

- implements one feature or fix and its directly related tests;
- can be explained by one commit subject;
- can be reviewed and, where practical, validated independently;
- does not depend on a later commit to avoid leaving the repository nonsensical.

Typical separate groups include implementation plus its tests, unrelated bug fixes, documentation, build/dependency changes, CI configuration, and formatting-only changes. Keep a test with the feature or fix it verifies unless the test itself is the standalone deliverable.

Before staging, state the proposed groups with their files or hunks and draft messages. If ownership or grouping is ambiguous and could commit unrelated user work, ask for direction; otherwise proceed.

## Stage one group at a time

Never default to:

```text
git add .
git add -A
git commit -am
```

Stage explicit paths:

```bash
git add -- path/to/file1 path/to/file2
```

When one file contains multiple logical changes, stage selected hunks with `git add -p -- path/to/file` in a PTY, or build and check an exact cached patch. Do not rewrite or discard the unstaged portion merely to simplify committing.

Review the exact staged snapshot:

```bash
git diff --cached --check
git diff --cached --stat
git diff --cached --name-status
git diff --cached
```

Confirm that the staged diff contains exactly one planned group and no secrets or unrelated edits. Run the smallest relevant test, formatter, build, or documentation validation for that group when practical.

## Commit and repeat

Validate the message, then commit:

```bash
python3 <skill-dir>/scripts/validate_commit_message.py 'feat(module): 增加目标功能'
git commit -m 'feat(module): 增加目标功能'
```

After each commit, run:

```bash
git show --stat --oneline --decorate HEAD
git status --short
```

Then stage and commit the next functional group. Do not amend, rebase, reset, clean, force, or push unless the user explicitly requests that separate action.

## Report the result

Report each commit hash, message, main files, and validation performed. Also list remaining modified or untracked files so the user knows what was intentionally not committed. If no changes are suitable, do not create an empty commit; explain why.