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:

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

Omit the parentheses when scope is unnecessary:

<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:

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:

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:

git add .
git add -A
git commit -am

Stage explicit paths:

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:

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:

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

After each commit, run:

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.