Back to Details

git-commit-workflow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Git Commit Workflow

Git 提交工作流

Expert guidance for commit message conventions, staging practices, and commit best practices using conventional commits and explicit staging workflows.
For detailed examples, advanced patterns, and best practices, see REFERENCE.md.
关于使用Conventional Commits和显式暂存工作流的提交信息规范、暂存实践与提交最佳实践的专业指南。
如需详细示例、高级模式与最佳实践，请参阅REFERENCE.md。

Core Expertise

核心专业内容

  • Conventional Commits: Standardized format for automation and clarity
  • Explicit Staging: Always stage files individually with clear visibility
  • Logical Grouping: Group related changes into focused commits
  • Communication Style: Humble, factual, concise commit messages
  • Pre-commit Integration: Run checks before committing
Note: Commits are made on main branch and pushed to remote feature branches for PRs. See git-branch-pr-workflow skill for the main-branch development pattern.
  • Conventional Commits：用于自动化与提升清晰度的标准化格式
  • 显式暂存：始终单独暂存文件，确保变更可见性
  • 逻辑分组：将相关变更归类为聚焦的提交
  • 沟通风格：谦逊、事实性、简洁的提交信息
  • 提交前集成：提交前运行检查
注意：提交在主分支上进行，并推送到远程特性分支以创建PR。有关主分支开发模式，请参阅git-branch-pr-workflow技能。

Conventional Commit Format

Conventional Commit 格式

Standard Format

标准格式

type(scope): description

[optional body]

[optional footer(s)]
For footer/trailer patterns (Co-authored-by, BREAKING CHANGE, Release-As), see git-commit-trailers skill.
type(scope): description

[可选正文]

[可选页脚]
有关页脚/尾部模式（Co-authored-by、BREAKING CHANGE、Release-As），请参阅git-commit-trailers技能。

Commit Types

提交类型

  • feat: New feature for the user
  • fix: Bug fix for the user
  • docs: Documentation changes
  • style: Formatting, missing semicolons, etc (no code change)
  • refactor: Code restructuring without changing behavior
  • test: Adding or updating tests
  • chore: Maintenance tasks, dependency updates, linter fixes
  • perf: Performance improvements
  • ci: CI/CD changes
  • feat：为用户新增功能
  • fix：为用户修复Bug
  • docs：文档变更
  • style：格式调整、缺失分号等（无代码逻辑变更）
  • refactor：代码重构，不改变功能行为
  • test：添加或更新测试
  • chore：维护任务、依赖更新、代码检查工具修复
  • perf：性能优化
  • ci：CI/CD 流程变更

Examples

示例

bash
undefined
bash
undefined

Feature with scope

带作用域的功能提交

git commit -m "feat(auth): implement OAuth2 integration"
git commit -m "feat(auth): implement OAuth2 integration"

Bug fix with body

带正文的Bug修复提交

git commit -m "fix(api): resolve null pointer in user service
Fixed race condition where user object could be null during concurrent authentication requests."
git commit -m "fix(api): resolve null pointer in user service
Fixed race condition where user object could be null during concurrent authentication requests."

Breaking change

破坏性变更提交

git commit -m "feat(api)!: migrate to GraphQL endpoints
BREAKING CHANGE: REST endpoints removed in favor of GraphQL. See migration guide at docs/migration.md"
undefined
git commit -m "feat(api)!: migrate to GraphQL endpoints
BREAKING CHANGE: REST endpoints removed in favor of GraphQL. See migration guide at docs/migration.md"
undefined

Commit Message Best Practices

提交信息最佳实践

DO:
  • Use imperative mood ("add feature" not "added feature")
  • Keep first line under 72 characters
  • Be concise and factual
  • ALWAYS reference related issues - every commit should link to relevant issues
  • Use GitHub closing keywords: 
    Fixes #123
    , 
    Closes #456
    , 
    Resolves #789
  • Use 
    Refs #N
    for related issues that should not auto-close
  • Use lowercase for type and scope
  • Be humble and modest
DON'T:
  • Use past tense ("added" or "fixed")
  • Include unnecessary details in subject line
  • Use vague descriptions ("update stuff", "fix bug")
  • Omit issue references - always link commits to their context
  • Use closing keywords (
    Fixes
    ) when you only mean to reference (
    Refs
    )
建议做法：
  • 使用祈使语气（如"add feature"而非"added feature"）
  • 首行长度不超过72个字符
  • 简洁且基于事实
  • 始终关联相关问题 - 每个提交都应链接到相关问题
  • 使用GitHub关闭关键字：
    Fixes #123
    、
    Closes #456
    、
    Resolves #789
  • 使用
    Refs #N
    关联不应自动关闭的相关问题
  • 类型与作用域使用小写字母
  • 保持谦逊、严谨的措辞
避免做法：
  • 使用过去式（如"added"或"fixed"）
  • 主题行包含不必要的细节
  • 使用模糊描述（如"update stuff"、"fix bug"）
  • 省略问题关联 - 始终为提交添加上下文链接
  • 当仅需关联问题时使用关闭关键字（
    Fixes
    ），应使用
    Refs
    替代

Pre-Commit Context Gathering (Recommended)

提交前上下文收集（推荐）

Before committing, gather all context in one command:
bash
undefined
提交前，通过一条命令收集所有上下文：
bash
undefined

Basic context: status, staged files, diff stats, recent log

基础上下文：状态、已暂存文件、差异统计、最近提交日志

bash "${CLAUDE_PLUGIN_ROOT}/skills/git-commit-workflow/scripts/commit-context.sh"
bash "${CLAUDE_PLUGIN_ROOT}/skills/git-commit-workflow/scripts/commit-context.sh"

With issue matching: also fetches open GitHub issues for auto-linking

带问题匹配：同时获取GitHub开放问题以自动关联

bash "${CLAUDE_PLUGIN_ROOT}/skills/git-commit-workflow/scripts/commit-context.sh" --with-issues

The script outputs: branch info, staged/unstaged status, diff stats, detected scopes, recent commit style, pre-commit config status, and optionally open issues. Use this output to compose the commit message. See [scripts/commit-context.sh](scripts/commit-context.sh) for details.
bash "${CLAUDE_PLUGIN_ROOT}/skills/git-commit-workflow/scripts/commit-context.sh" --with-issues

该脚本会输出：分支信息、已暂存/未暂存状态、差异统计、检测到的作用域、最近提交风格、提交前配置状态，以及可选的开放问题。使用此输出来编写提交信息。详情请参阅[scripts/commit-context.sh](scripts/commit-context.sh)。

Explicit Staging Workflow

显式暂存工作流

Always Stage Files Individually

始终单独暂存文件

bash
undefined
bash
undefined

Show current status

查看当前状态

git status --porcelain
git status --porcelain

Stage files one by one for visibility

逐个暂存文件以确保可见性

git add src/auth/login.ts git add src/auth/oauth.ts git status # Verify what's staged
git add src/auth/login.ts git add src/auth/oauth.ts git status # 验证已暂存内容

Show what will be committed

查看即将提交的内容

git diff --cached --stat git diff --cached # Review actual changes
git diff --cached --stat git diff --cached # 审查实际变更

Commit with conventional message

使用规范格式提交

git commit -m "feat(auth): add OAuth2 support"
undefined
git commit -m "feat(auth): add OAuth2 support"
undefined

Commit Message Formatting

提交信息格式化

HEREDOC Pattern (Required)

HEREDOC 模式（必填）

ALWAYS use HEREDOC directly in git commit.
bash
git commit -m "$(cat <<'EOF'
feat(auth): add OAuth2 support

Implements token refresh and secure storage.

Fixes #123
EOF
)"
始终在git commit中直接使用HEREDOC。
bash
git commit -m "$(cat <<'EOF'
feat(auth): add OAuth2 support

Implements token refresh and secure storage.

Fixes #123
EOF
)"

Communication Style

沟通风格

Humble, Fact-Based Messages

谦逊、基于事实的信息

bash
undefined
bash
undefined

Good: Concise, factual, modest

良好示例：简洁、事实性、严谨

git commit -m "fix(auth): handle edge case in token refresh"
git commit -m "feat(api): add pagination support
Implements cursor-based pagination for list endpoints. Includes tests and documentation."

Focus on facts: **What changed**, **Why it changed** (if non-obvious), and **Impact** (breaking changes).
git commit -m "fix(auth): handle edge case in token refresh"
git commit -m "feat(api): add pagination support
Implements cursor-based pagination for list endpoints. Includes tests and documentation."

聚焦于事实：**变更内容**、**变更原因**（如非显而易见），以及**影响**（如破坏性变更）。

Issue Reference Summary

问题关联汇总

ScenarioPatternExample
Bug fix resolving issue
Fixes #N
Fixes #123
Feature completing issue
Closes #N
Closes #456
Related but not completing
Refs #N
Refs #789
Cross-repository
Fixes owner/repo#N
Fixes org/lib#42
Multiple issuesRepeat keyword
Fixes #1, fixes #2
场景模式示例
修复Bug并解决问题
Fixes #N
Fixes #123
完成功能并关闭问题
Closes #N
Closes #456
关联但未完成问题
Refs #N
Refs #789
跨仓库关联
Fixes owner/repo#N
Fixes org/lib#42
多个问题重复关键字
Fixes #1, fixes #2

Best Practices

最佳实践

Commit Frequency

提交频率

  • Commit early and often: Small, focused commits
  • One logical change per commit: Easier to review and revert
  • Keep commits atomic: Each commit should be a complete, working state
  • 尽早提交、经常提交：小型、聚焦的提交
  • 每次提交对应一个逻辑变更：更易于审查与回滚
  • 保持提交原子性：每个提交应处于完整、可运行的状态

Commit Message Length

提交信息长度

bash
undefined
bash
undefined

Subject line: <= 72 characters

主题行：<= 72个字符

feat(auth): add OAuth2 support
feat(auth): add OAuth2 support

Body: <= 72 characters per line (wrap)

正文：每行<=72个字符（自动换行）

Use blank line between subject and body

主题与正文之间使用空行分隔

undefined
undefined

Agentic Optimizations

代理优化

ContextCommand
Pre-commit context
bash "${CLAUDE_PLUGIN_ROOT}/skills/git-commit-workflow/scripts/commit-context.sh"
Context + issues
bash "${CLAUDE_PLUGIN_ROOT}/skills/git-commit-workflow/scripts/commit-context.sh" --with-issues
Quick status
git status --porcelain
Staged diff stats
git diff --cached --stat
Recent commit style
git log --format='%s' -5
Open issues for linking
gh issue list --state open --json number,title --limit 30
上下文命令
提交前上下文
bash "${CLAUDE_PLUGIN_ROOT}/skills/git-commit-workflow/scripts/commit-context.sh"
上下文+问题
bash "${CLAUDE_PLUGIN_ROOT}/skills/git-commit-workflow/scripts/commit-context.sh" --with-issues
快速状态查看
git status --porcelain
已暂存差异统计
git diff --cached --stat
最近提交风格
git log --format='%s' -5
可关联的开放问题
gh issue list --state open --json number,title --limit 30