SuperAPI AI Directory

git-commit-helper

Coding & development

View repository

Updated 11-12 13:00

About this skill

Git Commit Assistant

Turn the changes produced by this task into clean, semantically clear commits. Core goal: make every git log record understandable within ten seconds—"what changed, and what kind of change it is".

Safety boundaries (highest priority)

  • Never commit automatically. Execute only if the user has explicitly said "提交/commit" in this conversation; a vague "finish it first" does not count. This is consistent with the constraints in the global CLAUDE.md.
  • Never git push。 This skill stops at commit. Push only when the user separately and explicitly requests a push.
  • Never git add -A / git add .。 Explicitly add file by file (adding an entire directory is allowed with git add <目录>/), to avoid accidentally committing unrelated files.
  • If suspected sensitive files (keys,.env, credentials, production configs containing passwords) or junk files (__pycache__、.venv, temporary artifacts, editor backups) appear in the pending commit list: stop, point this out to the user and confirm how to handle it; do not commit silently.

Workflow

1. Determine which changes are "the changes for this task"

Commit scope = the changes caused by this task, not everything dirty in the working tree.

git status --short          # 全貌:哪些文件被改/新增/未跟踪(首列为 M 表示已暂存)
git diff --cached --stat    # 暂存区是否已有内容

Determine each file's ownership against the conversation context. The working tree often contains leftover changes unrelated to this task (made by the user, or left over from a previous task)—leave thoseuntouched, keep them in the working tree, and mention "the following files were not included in the commit" in the final report.

  • The staging area already contains content unrelated to this task: stop and confirm with the user how to handle it (git restore --staged <文件> unstage it, or commit it separately),do not let it be swept into this commit。
  • A single file contains both this task's changes and unrelated user changes: confirm with the user first, and after the user agrees, use git add -p to stage only this task's hunks.
  • When unsure whether a file should be committed, ask; do not guess.

2. Decide whether to split into multiple commits

If this task is executed in multiple stages, each with an independent, clear goal (for example: first "optimize report SQL performance", then "update metric definition docs"; or "first fix the bug, then add the export feature"), thensplit into multiple commits by stage, adding the files involved in each stage separately before committing. Criteria:

  • After splitting, can each commit clearly describe one thing on its own? If it can be split, split it.
  • Do the two batches of files serve two different intents (one fix, one feat)? Split them.
  • Are they related modifications incidentally produced by one logical change (e.g., changing a metric definition and updating the corresponding docs at the same time)?Do not split; put them in the same commit.

3. Write the commit message

Format:类型: 一句话简述(Chinese; a full-width colon is also acceptable; follow the repository's existing style—first run git log --oneline -5 to take a look).

Type selection:

Type Used for
feat new features, new reports, new scripts, new metrics
fix Fix bugs, correct incorrect definitions, fix SQL logic errors
refactor Changes that do not alter external behavior: renaming, structural reorganization, column name adjustments
perf Performance optimization (e.g., slow SQL optimization, index adjustments)
docs Documentation/definition clarification changes only
chore Chores: configuration, ignore rules, dependency upgrades, etc.
test Test-only changes

Summary requirements:

  • One sentence, verb-object structure, directly state what was done. About 30 characters or fewer is appropriate.
  • Accurately cover the content but do not list details: report-related changes should include report numbers (e.g., "reports 162/147/148"); do not write "modified 3 files".
  • No empty phrases ("updated code", "some modifications", "improved functionality"); no long body paragraphs; no extraneous information.

Examples:

Input: This time, a collection recovery rate metric column was added to report 31, and the corresponding definition documentation was updated in sync Output: feat: 报表31新增催回率指标列及口径文档同步

Input: Fixed the issue where the repayment plan query failed to exclude canceled bills, causing overdue statistics to be too high Output: fix: 修复已取消账单未排除导致逾期统计偏高

Input: The task has two phases—first optimize the slow SQL of report 11, then separately organize the parameter validation of the export script Output (two entries):

perf: 报表11渠道流量监控SQL性能优化
fix: 导出脚本补充批次参数校验

4. Execute commit

For each commit unit:

git add <文件1> <文件2> ...      # 显式逐个列出(整目录新增可用 `git add <目录>/`)
git diff --cached --stat          # 核对暂存内容与本次意图一致
git commit -m "类型: 一句话简述"

When there are multiple commit units, loop "add → verify → commit", keeping the staging area clean each time and containing only the files for that phase.

5. Final report

After committing, briefly report to the user:

  • git log --oneline List the commits just created;
  • Leftover files in the working tree not included in the commit (if any);
  • Clearly statepush was not executed。

Exception handling

  • Working tree is clean (no changes from this task): inform the user there is nothing to commit and do not touch git.
  • Commit is blocked by a pre-commit hook (lint/commitlint checks, lock files, etc.): truthfully report the error content,without the user's explicit request, do not use --no-verify to bypass。
  • Repository has conflicts, is in a merge intermediate state, or detached HEAD: stop and report the current state, waiting for user instructions.
  • A file specified by the user does not exist in git status: truthfully explain, do not fabricate a commit.
  • Accidentally added a file: use git restore --staged <文件> to unstage it; do not use git reset --hard or other destructive commands to revert.