git-commit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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

步骤

  1. 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.
    package.json
    scripts,
    Makefile
    ,
    justfile
    ,
    cargo
    ,
    go
    ,
    mix
    ,
    pytest
    ).
    Example (bun + TypeScript):
    bash
    bun run type-check
    bun test
    bun run lint
    bun run fmt
    If any fails, stop and fix the issue before committing.
  2. Check what will be staged:
    bash
    git status
    git diff --stat
  3. 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.
  4. Stage the relevant files for the current commit. Be explicit. Do not use
    git add -A
    blindly:
    bash
    git add apps/api/src/modules/projects/
    git add apps/api/src/db/migrations/0003_add_project_archive.sql
    # etc.
    Never stage:
    • .env
      files
    • *.pem
      key files
    • 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__/
      )
  5. Compose the commit message. First check the project's own convention:
    CONTRIBUTING.md
    , a
    commitlint.config.*
    file, a commit-msg hook, and the style of
    git log --oneline -20
    . The project's convention wins. Where it says nothing, use Conventional Commits:
    Format:
    <type>(<scope>): <subject>
    TypeUse when
    feat
    New feature or behavior
    fix
    Bug fix
    refactor
    Code change with no behavior change
    test
    Adding or fixing tests
    docs
    Documentation changes only
    chore
    Build config, tooling, dependency updates
    perf
    Performance improvement
    Scope: the module or layer changed (e.g.,
    auth
    ,
    tasks
    ,
    gantt
    ,
    db
    ,
    ci
    )
    Subject rules:
    • Imperative mood: "add", "fix", "refactor", not "added" or "fixing"
    • Max 80 characters for the entire first line (
      type(scope): subject [ID]
      combined). A commit-msg hook (e.g. husky/commitlint) often enforces this for the subject line.
    • No period at end
    • Reference task ID when applicable:
      [BE-S2-02]
    • Never write
      @<name>
      or
      @<digit>
      anywhere in the message.
      GitHub renders
      @something
      as a user mention and notifies whoever owns that handle. For version pins, write
      v4
      /
      v5
      ,
      major 4
      , or wrap in backticks (
      `@4`
      ). The same rule applies to commit bodies, PR titles, PR bodies, issue comments, and release notes.
    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:
    bash
    awk 'length > 80 { print "TOO LONG (" length "): " $0 }' /tmp/commit-msg.txt
    git commit -F /tmp/commit-msg.txt
    No output from
    awk
    means every line fits.
    For quick subject-only checks:
    bash
    echo -n "chore(auth): remove readme artifact and fix ErrorBoundary [FE-AUTH-06]" | wc -c
    # must be 80 or fewer
  6. 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):
    bash
    git 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 add
    Co-Authored-By
    trailers.
    Commits are authored solely by the developer. No AI attribution lines.
  7. Repeat for the next logical commit if the working tree still has unstaged changes from a different intent. Return to step 3.
  8. Verify the commits:
    bash
    git log --oneline -5
  9. Report to the user: commit hashes and messages for every commit you made.
  1. 执行最终验证。所有检查必须通过。 使用项目自身的门禁:类型检查(如果所用语言支持)、测试、lint 和 format。阅读项目清单 / 任务运行器以确定准确的命令(例如
    package.json
    scripts、
    Makefile
    、
    justfile
    、
    cargo
    、
    go
    、
    mix
    、
    pytest
    )。
    示例(bun + TypeScript):
    bash
    bun run type-check
    bun test
    bun run lint
    bun run fmt
    如果任何检查失败,请停止操作,修复问题后再提交。
  2. 检查将要暂存的内容:
    bash
    git status
    git diff --stat
  3. 拆分为逻辑独立的提交。 暂存前扫描 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"
    不确定两个更改是否应放在一起时,可以使用以下判断标准:「有人是否可能希望在不撤销另一个的情况下撤销其中一个?」如果是,则拆分。
  4. 为当前提交暂存相关文件。 明确指定文件。不要盲目使用
    git add -A
    :
    bash
    git 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__/
      )
  5. 编写提交信息。 首先检查项目自身的约定:
    CONTRIBUTING.md
    、
    commitlint.config.*
    文件、
    commit-msg
    hook,以及
    git log --oneline -20
    中的风格。项目的约定优先。如果没有任何说明,则使用 Conventional Commits:
    格式:
    <type>(<scope>): <subject>
    类型使用场景
    feat
    新功能或新行为
    fix
    Bug 修复
    refactor
    无行为变化的代码更改
    test
    新增或修复测试
    docs
    仅文档更改
    chore
    构建配置、工具、依赖更新
    perf
    性能改进
    Scope:发生更改的模块或层级(例如
    auth
    、
    tasks
    、
    gantt
    、
    db
    、
    ci
    )
    主题规则:
    • 使用祈使语气:使用「add」、「fix」、「refactor」,不要使用「added」或「fixing」
    • 整个首行最多 80 个字符(
      type(scope): subject [ID]
      合并计算)。commit-msg hook(例如 husky/commitlint)通常会强制限制主题行的长度。
    • 结尾不写句号
    • 适用时引用任务 ID:
      [BE-S2-02]
    • 绝不要在消息中的任何位置写入
      @<name>
      或
      @<digit>
      。
      GitHub 会将
      @something
      渲染为用户提及,并通知该账号的所有者。对于版本固定,请写
      v4
      /
      v5
      、
      major 4
      ,或使用反引号包裹(
      `@4`
      )。同样的规则适用于提交正文、PR 标题、PR 正文、issue 评论和 release notes。
    正文规则(适用于多行提交):
    • 正文中的每一行也限制在 80 个字符以内。 手动对长句换行。
    • 主题和正文之间空一行。
    • 正文各段之间空一行。
    提交前,将消息写入文件并检查每一行:
    bash
    awk 'length > 80 { print "TOO LONG (" length "): " $0 }' /tmp/commit-msg.txt
    git commit -F /tmp/commit-msg.txt
    awk
    没有输出意味着每一行都符合长度要求。
    如需快速检查主题行:
    bash
    echo -n "chore(auth): remove readme artifact and fix ErrorBoundary [FE-AUTH-06]" | wc -c
    # must be 80 or fewer
  6. 创建提交:
    bash
    git commit -m "feat(projects): add project creation endpoint [BE-S2-02]"
    对于多行提交(当「为什么」不明显时):
    bash
    git 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."
    不要添加
    Co-Authored-By
    trailer。
    提交仅由开发者本人署名。不得添加 AI 归属信息。
  7. 如果工作区仍有来自其他意图的未暂存更改,请为下一个逻辑提交重复上述步骤。 返回步骤 3。
  8. 验证提交:
    bash
    git log --oneline -5
  9. 向用户报告: 列出你创建的每个提交的哈希和信息。

Creating a GitHub Release

创建 GitHub Release

When the commit is a release (
chore: release vX.Y.Z
) and the version bump has landed on the default branch, cut the release.
  1. 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.md
    Only if the project requires signed tags (OpenSSF Best Practices Gold
    version_tags_signed
    , or an org supply-chain policy):
    gh release create --target
    makes an unsigned server-side tag, and
    tag.gpgSign=true
    does 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 (no
    --target
    ):
    bash
    git 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
  2. The title is the version and nothing else:
    vX.Y.Z
    . No tagline, no emoji, no "Release", no emoji, no summary. The body carries the detail.
  3. The body is written by the
    release-notes
    skill.
    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
    @<name>
    /
    @<digit>
    rule applies there too: never in release notes (use
    v4
    or backticks).
  4. Verify after publish: the publish workflow run is green and the registry shows the new version (
    npm view <pkg> version
    , JSR
    meta.json
    ); signed release artifacts are attached if the project signs them.
当提交是发布提交(
chore: release vX.Y.Z
),且版本号提升已合入默认分支后,即可创建 Release。
  1. 创建标签和 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
    会创建一个未签名的服务端标签,而且
    tag.gpgSign=true
    不起作用,因为 gh 在服务端创建标签,绕过了本地 git 签名。你必须在本地创建标签(这样会按照配置进行签名),推送标签,然后基于已有标签创建 Release(不要使用
    --target
    ):
    bash
    git 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
  2. 标题只能是版本号,不能有其他内容:
    vX.Y.Z
    。不要添加宣传语、emoji、
    Release
    、emoji 或摘要。详情放在正文中。
  3. 正文由
    release-notes
    skill 编写。
    应调用该 skill,而不是直接粘贴 CHANGELOG 章节:changelog 是面向现有用户的完整记录,而 release notes 是供决定是否采用的人阅读。只陈述事实:不要营销,不要填充内容(诸如「we're excited to」、「huge improvements」),不要添加无意义的话。
    @<name>
    /
    @<digit>
    规则同样适用:release notes 中绝不能出现这些内容(请使用
    v4
    或反引号)。
  4. 发布后进行验证: publish workflow run 为绿色,registry 显示新版本(
    npm view <pkg> version
    、JSR
    meta.json
    );如果项目对 release artifacts 进行签名,则确认已附加签名后的 release artifacts。

Checklist Before Done

完成前检查清单

  • Type-check passed (if the language has one)
  • Tests passed
  • Lint passed
  • Format passed
  • No
    .env
    files staged
  • No
    *.pem
    key files staged
  • 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
    @<name>
    or
    @<digit>
    anywhere in subject or body (use
    v5
    or backticks for version pins)
  • 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
undefined
bash
undefined

Good

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 #
@4
/
@5
become user mentions fix: do thing and also bump version # two intents: split into two commits
undefined
update code fix bug WIP added the task thing chore: bump demo CDN pin from @4 to @5 #
@4
/
@5
become user mentions fix: do thing and also bump version # two intents: split into two commits
undefined