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"

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"

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

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

问题关联汇总

Scenario	Pattern	Example
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 issues	Repeat 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

Body: <= 72 characters per line (wrap)

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

Use blank line between subject and body

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

undefined

undefined

Agentic Optimizations

代理优化

Context	Command
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`