git-commit
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseSkill: git-commit
Skill: git-commit
When to Use
使用时机
You have completed a task, all verifications have passed, and you need to commit the changes.
你已完成一项任务,所有验证均已通过,并且需要提交更改。
Steps
步骤
-
Run final verification. All checks must pass. Use the project's own gate: type-check (if the language has one), tests, lint, and format. Read the project manifest / task runner for the exact commands (e.g.scripts,
package.json,Makefile,justfile,cargo,go,mix).pytestExample (bun + TypeScript):bashbun run type-check bun test bun run lint bun run fmtIf any fails, stop and fix the issue before committing. -
Check what will be staged:bash
git status git diff --stat -
Split into logical commits. Before staging, scan the diff and group changes by intent. Do not put unrelated changes into one commit. A commit should answer a single "why."Common splits:
- Bug fix vs version bump -> two commits
- Source code change vs test additions for an unrelated module -> two commits
- Refactor vs new feature -> two commits
- Code change vs docs/CHANGELOG update for that same code -> can be one commit
- Code change vs unrelated formatting noise -> two commits (or revert the noise)
If the working tree has multiple intents, commit them in sequence:bash# Commit 1: the fix git add src/auth/session.ts tests/auth/session.test.ts git commit -m "fix(auth): handle expired refresh token gracefully" # Commit 2: the version bump (separate intent) git add package.json jsr.json git commit -m "chore: bump version to 5.4.2"When uncertain whether two changes belong together, the test is: "Could someone want to revert one without the other?" If yes, split. -
Stage the relevant files for the current commit. Be explicit. Do not useblindly:
git add -Abashgit add apps/api/src/modules/projects/ git add apps/api/src/db/migrations/0003_add_project_archive.sql # etc.Never stage:- files
.env - key files
*.pem - Lockfile changes for unrelated packages (e.g. ,
bun.lock,package-lock.json,Cargo.lock,go.sum)poetry.lock - Build output (e.g. ,
dist/,.next/,target/,build/)__pycache__/
-
Compose the commit message. First check the project's own convention:, a
CONTRIBUTING.mdfile, a commit-msg hook, and the style ofcommitlint.config.*. The project's convention wins. Where it says nothing, use Conventional Commits:git log --oneline -20Format:<type>(<scope>): <subject>Type Use when featNew feature or behavior fixBug fix refactorCode change with no behavior change testAdding or fixing tests docsDocumentation changes only choreBuild config, tooling, dependency updates perfPerformance improvement Scope: the module or layer changed (e.g.,,auth,tasks,gantt,db)ciSubject rules:- Imperative mood: "add", "fix", "refactor", not "added" or "fixing"
- Max 80 characters for the entire first line (combined). A commit-msg hook (e.g. husky/commitlint) often enforces this for the subject line.
type(scope): subject [ID] - No period at end
- Reference task ID when applicable:
[BE-S2-02] - Never write or
@<name>anywhere in the message. GitHub renders@<digit>as a user mention and notifies whoever owns that handle. For version pins, write@something/v4,v5, or wrap in backticks (major 4). The same rule applies to commit bodies, PR titles, PR bodies, issue comments, and release notes.`@4`
Body rules (for multi-line commits):- Every line in the body is also capped at 80 characters. Hard-wrap long sentences manually.
- One blank line between subject and body.
- One blank line between paragraphs in the body.
Before committing, write the message to a file and check every line:bashawk 'length > 80 { print "TOO LONG (" length "): " $0 }' /tmp/commit-msg.txt git commit -F /tmp/commit-msg.txtNo output frommeans every line fits.awkFor quick subject-only checks:bashecho -n "chore(auth): remove readme artifact and fix ErrorBoundary [FE-AUTH-06]" | wc -c # must be 80 or fewer -
Create the commit:bash
git commit -m "feat(projects): add project creation endpoint [BE-S2-02]"For multi-line commits (when the "why" is non-obvious):bashgit commit -m "feat(tasks): enforce finish-to-start dependency [BE-S3-03] Task B's checkbox is disabled when its prerequisite (Task A) is not yet in completed status. Auto-unlock triggers after Task A completes, changing Task B from locked to ready."Do NOT addtrailers. Commits are authored solely by the developer. No AI attribution lines.Co-Authored-By -
Repeat for the next logical commit if the working tree still has unstaged changes from a different intent. Return to step 3.
-
Verify the commits:bash
git log --oneline -5 -
Report to the user: commit hashes and messages for every commit you made.
-
执行最终验证。所有检查必须通过。 使用项目自身的门禁:类型检查(如果所用语言支持)、测试、lint 和 format。阅读项目清单 / 任务运行器以确定准确的命令(例如scripts、
package.json、Makefile、justfile、cargo、go、mix)。pytest示例(bun + TypeScript):bashbun run type-check bun test bun run lint bun run fmt如果任何检查失败,请停止操作,修复问题后再提交。 -
检查将要暂存的内容:bash
git status git diff --stat -
拆分为逻辑独立的提交。 暂存前扫描 diff,并按意图分组。不要把不相关的更改放入同一个提交。 每次提交都应只回答一个「为什么」。常见拆分方式:
- Bug 修复与版本号提升 -> 两次提交
- 源代码更改与另一个无关模块的测试新增 -> 两次提交
- 重构与新功能 -> 两次提交
- 代码更改与同一代码对应的 docs/CHANGELOG 更新 -> 可合为一次提交
- 代码更改与无关的格式变更噪声 -> 两次提交(或回退这些噪声)
如果工作区中存在多种意图的更改,请依次提交:bash# Commit 1: the fix git add src/auth/session.ts tests/auth/session.test.ts git commit -m "fix(auth): handle expired refresh token gracefully" # Commit 2: the version bump (separate intent) git add package.json jsr.json git commit -m "chore: bump version to 5.4.2"不确定两个更改是否应放在一起时,可以使用以下判断标准:「有人是否可能希望在不撤销另一个的情况下撤销其中一个?」如果是,则拆分。 -
为当前提交暂存相关文件。 明确指定文件。不要盲目使用:
git add -Abashgit add apps/api/src/modules/projects/ git add apps/api/src/db/migrations/0003_add_project_archive.sql # etc.绝不能暂存:- 文件
.env - 密钥文件
*.pem - 与无关依赖包相关的 lockfile 更改(例如 、
bun.lock、package-lock.json、Cargo.lock、go.sum)poetry.lock - 构建产物(例如 、
dist/、.next/、target/、build/)__pycache__/
-
编写提交信息。 首先检查项目自身的约定:、
CONTRIBUTING.md文件、commitlint.config.*hook,以及commit-msg中的风格。项目的约定优先。如果没有任何说明,则使用 Conventional Commits:git log --oneline -20格式:<type>(<scope>): <subject>类型 使用场景 feat新功能或新行为 fixBug 修复 refactor无行为变化的代码更改 test新增或修复测试 docs仅文档更改 chore构建配置、工具、依赖更新 perf性能改进 Scope:发生更改的模块或层级(例如、auth、tasks、gantt、db)ci主题规则:- 使用祈使语气:使用「add」、「fix」、「refactor」,不要使用「added」或「fixing」
- 整个首行最多 80 个字符(合并计算)。commit-msg hook(例如 husky/commitlint)通常会强制限制主题行的长度。
type(scope): subject [ID] - 结尾不写句号
- 适用时引用任务 ID:
[BE-S2-02] - 绝不要在消息中的任何位置写入 或
@<name>。 GitHub 会将@<digit>渲染为用户提及,并通知该账号的所有者。对于版本固定,请写@something/v4、v5,或使用反引号包裹(major 4)。同样的规则适用于提交正文、PR 标题、PR 正文、issue 评论和 release notes。`@4`
正文规则(适用于多行提交):- 正文中的每一行也限制在 80 个字符以内。 手动对长句换行。
- 主题和正文之间空一行。
- 正文各段之间空一行。
提交前,将消息写入文件并检查每一行:bashawk 'length > 80 { print "TOO LONG (" length "): " $0 }' /tmp/commit-msg.txt git commit -F /tmp/commit-msg.txt没有输出意味着每一行都符合长度要求。awk如需快速检查主题行:bashecho -n "chore(auth): remove readme artifact and fix ErrorBoundary [FE-AUTH-06]" | wc -c # must be 80 or fewer -
创建提交:bash
git commit -m "feat(projects): add project creation endpoint [BE-S2-02]"对于多行提交(当「为什么」不明显时):bashgit commit -m "feat(tasks): enforce finish-to-start dependency [BE-S3-03] Task B's checkbox is disabled when its prerequisite (Task A) is not yet in completed status. Auto-unlock triggers after Task A completes, changing Task B from locked to ready."不要添加trailer。 提交仅由开发者本人署名。不得添加 AI 归属信息。Co-Authored-By -
如果工作区仍有来自其他意图的未暂存更改,请为下一个逻辑提交重复上述步骤。 返回步骤 3。
-
验证提交:bash
git log --oneline -5 -
向用户报告: 列出你创建的每个提交的哈希和信息。
Creating a GitHub Release
创建 GitHub Release
When the commit is a release () and the version bump has
landed on the default branch, cut the release.
chore: release vX.Y.Z-
Create the tag and release. For most repos, the one-liner is fine: it creates the tag at the branch tip:bash
gh release create vX.Y.Z --target main --title "vX.Y.Z" --notes-file notes.mdOnly if the project requires signed tags (OpenSSF Best Practices Gold, or an org supply-chain policy):version_tags_signedmakes an unsigned server-side tag, andgh release create --targetdoes NOT help, because gh creates the tag server-side, bypassing local git signing. You must tag locally (which signs per config), push it, then create the release from the existing tag (notag.gpgSign=true):--targetbashgit tag -s vX.Y.Z <commit> -m "vX.Y.Z" # signed (gpg or ssh-format key) git push origin vX.Y.Z gh release create vX.Y.Z --title "vX.Y.Z" --notes-file notes.md # no --target git verify-tag vX.Y.Z -
The title is the version and nothing else:. No tagline, no emoji, no "Release", no emoji, no summary. The body carries the detail.
vX.Y.Z -
The body is written by theskill. Invoke it rather than pasting the CHANGELOG section in: the changelog is the complete record for existing users, the notes are for someone deciding whether to adopt. State facts only: no marketing, no filler ("we're excited to", "huge improvements"), no slop. The
release-notes/@<name>rule applies there too: never in release notes (use@<digit>or backticks).v4 -
Verify after publish: the publish workflow run is green and the registry shows the new version (, JSR
npm view <pkg> version); signed release artifacts are attached if the project signs them.meta.json
当提交是发布提交(),且版本号提升已合入默认分支后,即可创建 Release。
chore: release vX.Y.Z-
创建标签和 Release。 对于大多数仓库,使用单行命令即可: 它会在分支顶端创建标签:bash
gh release create vX.Y.Z --target main --title "vX.Y.Z" --notes-file notes.md仅当项目要求使用“签名标签”时(OpenSSF Best Practices Gold,或组织的供应链策略):version_tags_signed会创建一个未签名的服务端标签,而且gh release create --target不起作用,因为 gh 在服务端创建标签,绕过了本地 git 签名。你必须在本地创建标签(这样会按照配置进行签名),推送标签,然后基于已有标签创建 Release(不要使用tag.gpgSign=true):--targetbashgit tag -s vX.Y.Z <commit> -m "vX.Y.Z" # signed (gpg or ssh-format key) git push origin vX.Y.Z gh release create vX.Y.Z --title "vX.Y.Z" --notes-file notes.md # no --target git verify-tag vX.Y.Z -
标题只能是版本号,不能有其他内容:。不要添加宣传语、emoji、
vX.Y.Z、emoji 或摘要。详情放在正文中。Release -
正文由skill 编写。 应调用该 skill,而不是直接粘贴 CHANGELOG 章节:changelog 是面向现有用户的完整记录,而 release notes 是供决定是否采用的人阅读。只陈述事实:不要营销,不要填充内容(诸如「we're excited to」、「huge improvements」),不要添加无意义的话。
release-notes/@<name>规则同样适用:release notes 中绝不能出现这些内容(请使用@<digit>或反引号)。v4 -
发布后进行验证: publish workflow run 为绿色,registry 显示新版本(、JSR
npm view <pkg> version);如果项目对 release artifacts 进行签名,则确认已附加签名后的 release artifacts。meta.json
Checklist Before Done
完成前检查清单
- Type-check passed (if the language has one)
- Tests passed
- Lint passed
- Format passed
- No files staged
.env - No key files staged
*.pem - Unrelated changes split into separate commits (one intent per commit)
- Commit message follows Conventional Commits format
- Scope matches the affected module
- Subject uses imperative mood
- Subject line is 80 characters or fewer (verified with )
echo -n "..." | wc -c - Every body line is 80 characters or fewer
- No or
@<name>anywhere in subject or body (use@<digit>or backticks for version pins)v5 - Task ID referenced in subject when applicable
- 类型检查已通过(如果所用语言支持)
- 测试已通过
- Lint 已通过
- Format 已通过
- 未暂存任何 文件
.env - 未暂存任何 密钥文件
*.pem - 不相关的更改已拆分为独立提交(每个提交只包含一个意图)
- 提交信息遵循 Conventional Commits 格式
- Scope 与受影响的模块一致
- 主题使用祈使语气
- 主题行不超过 80 个字符(已通过 验证)
echo -n "..." | wc -c - 正文每一行都不超过 80 个字符
- 主题或正文中任何位置都没有 或
@<name>(版本固定使用@<digit>或反引号)v5 - 适用时主题中引用了任务 ID
Examples
示例
bash
undefinedbash
undefinedGood
Good
feat(tasks): add dependency enforcement on task completion [BE-S3-03]
fix(auth): handle expired refresh token gracefully
test(projects): add service unit tests for template change [BE-S2-11]
chore(ci): add coverage threshold check to CI workflow
docs(onboarding): update setup steps for Docker dev environment
chore: bump demo CDN pin from v4 to v5
feat(tasks): add dependency enforcement on task completion [BE-S3-03]
fix(auth): handle expired refresh token gracefully
test(projects): add service unit tests for template change [BE-S2-11]
chore(ci): add coverage threshold check to CI workflow
docs(onboarding): update setup steps for Docker dev environment
chore: bump demo CDN pin from v4 to v5
Bad
Bad
update code
fix bug
WIP
added the task thing
chore: bump demo CDN pin from @4 to @5 # / become user mentions
fix: do thing and also bump version # two intents: split into two commits
@4@5undefinedupdate code
fix bug
WIP
added the task thing
chore: bump demo CDN pin from @4 to @5 # / become user mentions
fix: do thing and also bump version # two intents: split into two commits
@4@5undefined