Before committing, first keep noise out of the repository, then write a standardized message. The core isexclusion list + ignore destination decisiontwo things; the git commit itself is the tail end.
🔴 Hard rules (guardrail, violation means failure)
- Do not push proactively. What to do instead: only
add+commit; pushing is performed only after an explicit user instruction. - Never commit suspected secrets/credentials. What to do instead: on a hit, 🔴 STOP, raise an alert, and list the files, prompting the user to rotate the credentials + clean history as appropriate (ignore only blocks untracked files; what has already leaked will not disappear because of ignoring). For the detection list, see references/secrets-and-cleanup.md。
Positive recipe (rewritten from negative items)
- Before deleting tracked files (
git rm --cached), firstgit rm -n --cacheddry-run to produce a list, report it to the user, and execute only after confirmation — this change will propagate to collaborators' workspaces. - Add
git add <path>one by one, with paths taken from the output of the previous stepgit status --porcelain, to avoid noise and secrets being swept into the staging area together.
Workflow
1. Look at the changes
git status --porcelain
git diff --stat # 已追踪改动量
Completion criteria: the full list of files changed this time (including additions/modifications/deletions) and the line-count statistics for tracked changes have been obtained, so each item can be classified accordingly.
2. Classify: should commit vs noise
Classify file by file. The complete classification table of high-frequency noise/keep list/destination criteriasingle source of truthsee references/noise-and-ignore.md(§1 noise classification, §2 lock files and metadata files that should be kept, §3 ignore destination decision).
Completion criteria: every file in the list has been classified into either "should commit" or "noise (to be excluded)", with no omissions; files matching the §1 secret-type pattern have been separately marked and handed over to hard rule 2.
3. Ignore destination decision (the user's core requirement)
Whether the excluded noise should be written to the ignore list, and where, is determined by references/noise-and-ignore.md §3。
- Before appending, first
git check-ignore -v <path>: output means it is already ignored by some rule (with the source file attached), so do not add it again. - Only append the patterns that hit, do not stuff in a hundred-line template.
Completion criteria: every ignore pattern newly added this time has been confirmed to have git check-ignore -v no previous output (not already covered), and has been written to the destination file corresponding to the §3 criteria.
4. Noise that is already tracked
.gitignore only handles untracked files; tracked ones need to be removed from the index (must include --cached, otherwise the local file is deleted):
git rm -n --cached <path> # dry-run 预演,列清单待用户确认(见正向配方)
git rm --cached <path> # 单文件;目录加 -r
# 再把 pattern 写入对应忽略落点
Completion criteria: for every file judged this time as "tracked noise", the index-removal list has been confirmed by the user; after confirmation, git rm --cached has actually been executed and the corresponding ignore pattern has been written to disk.
5. Stage + commit
git diff --cached | grep -nE -- '-----BEGIN [A-Z ]*PRIVATE KEY-----|AKIA[0-9A-Z]{16}|ghp_|glpat-|sk-(ant-|proj-)?' # 密钥预扫,命中 STOP
git add <应提交项...> # 逐个加(见正向配方)
git diff --cached --quiet && echo "无暂存改动,不空提交" # 防空提交
git commit -m "<type>(<scope>): <subject>"
commit message:The user has already provided a message in the input → use it directly, do not invent one; only generate automatically if none was given —feat/fix/docs/refactor/chore/test/perf/build/ci + imperative-mood subject,first git log --oneline -20 sample the project style before writing(measured in this project: type/scope in English, subject in Chinese, e.g. feat(trellisx): 异步等待...). For detailed conventions, see references/secrets-and-cleanup.md §message。
Completion criteria: The secret pre-scan command has been run with no hits (or hits have been handled per Hard Rule 2 and aborted);git commit A new commit hash has been successfully returned, or "nothing to commit" has been explicitly reported.
Failure handling (trigger condition → first-line fix → fallback if still failing)
| Trigger condition | First-line fix | Fallback if still failing |
|---|---|---|
| Suspected secret hit | 🔴 STOP, list files and alert,git restore --staged <file> remove from |
Already tracked → warn that the secret has entered history, must rotate + git filter-repo purge history (do not execute on behalf) |
git add Reports path does not exist/special characters |
Use -- separator + quotes:git add -- '<path>' |
Add file by file, skip erroring items and list them |
| No substantive changes (all noise) | Report "nothing to commit, ignore list updated", do not make an empty commit | User insists → --allow-empty requires explicit request |
| pre-commit hook blocks the commit | Read hook output, fix root cause (lint/format) then re-commit | Cannot fix → report the original text,--no-verify use only when the user explicitly states |
| Large file (>50MB) accidentally staged | Suggest Git LFS (git lfs track) or remove |
User insists → warn that repo bloat is irreversible, then hand over |
| Whole-file spurious diff (CRLF/mode) | .gitattributes * text=auto / core.fileMode false |
If confirmed not a real content change, do not commit that item |
Honesty boundaries
- Only blocksuntrackednoise and newly added ignores; secrets/large files already in history are not purged by this skill (the user needs to run
git filter-repo)。 - Noise patterns are high-frequency items, not exhaustive; obscure artifact directories require the user to supplement judgment.
- Secret detection is heuristic (filename + content clues), and may miss/false-positive; for precise rules, defer to gitleaks/GitHub secret-scanning.
- Does not modify commit history (no amend/rebase); to change history, use git-rebase or an explicit user instruction.