Back to Details

git-commit-flow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Git Commit Flow Skill

Git Commit Flow 技能

Operator Context

操作场景

This skill operates as an operator for git commit workflows, configuring Claude's behavior for standardized commit creation with quality enforcement. It implements a 4-phase gate pattern: VALIDATE, STAGE, COMMIT, VERIFY.
本技能作为Git提交工作流的操作器，配置Claude的行为以实现带质量管控的标准化提交。它采用四阶段门控模式：VALIDATE、STAGE、COMMIT、VERIFY。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

  • CLAUDE.md Compliance: Read and follow repository CLAUDE.md before execution. Enforce banned patterns ("Generated with Claude Code", "Co-Authored-By: Claude") in all commit messages
  • Sensitive File Blocking: NEVER commit 
    .env
    , 
    *credentials*
    , 
    *secret*
    , 
    *.pem
    , 
    *.key
    , 
    .npmrc
    , 
    .pypirc
    . Hard fail if detected in staging area
  • Over-Engineering Prevention: Only implement the requested commit workflow. No speculative features, no "while I'm here" improvements
  • Atomic Operations: Each phase gate must pass before proceeding. No partial commits
  • Branch Protection: Warn and require confirmation before committing to main/master
  • No Skipped Phases: Execute all 4 phases sequentially. Never skip validation
  • CLAUDE.md合规性：执行前读取并遵循仓库的CLAUDE.md文件。强制禁止所有提交消息中出现禁用模式（如「Generated with Claude Code」「Co-Authored-By: Claude」）
  • 敏感文件拦截：绝对禁止提交
    .env
    、
    *credentials*
    、
    *secret*
    、
    *.pem
    、
    *.key
    、
    .npmrc
    、
    .pypirc
    文件。若在暂存区检测到此类文件，直接终止流程
  • 过度设计预防：仅实现请求的提交工作流，不添加推测性功能，不进行顺手的额外改进
  • 原子操作：必须通过前一阶段门控才能进入下一阶段，不允许部分提交
  • 分支保护：提交到main/master分支前会发出警告并要求确认
  • 阶段不跳过：按顺序执行全部4个阶段，绝不跳过验证环节

Default Behaviors (ON unless disabled)

默认行为（默认开启，可关闭）

  • Interactive Confirmation: Show staging plan and commit message for user approval before executing
  • Conventional Commit Enforcement: Validate message follows 
    <type>[scope]: <description>
    format
  • Working Tree Validation: Check for clean state (no merge/rebase in progress) before starting
  • Smart File Staging: Group files by type (docs, code, config, tests, CI) for logical commits
  • Post-Commit Verification: Confirm commit exists in log and working tree is clean after commit
  • Temporary File Cleanup: Remove validation artifacts created during workflow
  • 交互式确认：执行前展示暂存计划和提交消息，等待用户确认
  • 规范化提交强制检查：验证提交消息是否符合
    <type>[scope]: <description>
    格式
  • 工作区验证：开始前检查工作区是否处于干净状态（无合并/变基操作进行中）
  • 智能文件暂存：按文件类型（文档、代码、配置、测试、CI）分组，实现逻辑化提交
  • 提交后校验：提交完成后确认提交已记录到日志且工作区保持干净
  • 临时文件清理：移除工作流过程中生成的验证 artifacts

Optional Behaviors (OFF unless enabled)

可选行为（默认关闭，可开启）

  • Auto-Stage All: Stage all modified files without confirmation (
    --auto-stage
    )
  • Skip Validation: Bypass conventional commit format checks (
    --skip-validation
    )
  • Dry Run Mode: Show what would be committed without executing (
    --dry-run
    )
  • Push After Commit: Automatically push to remote after success (
    --push
    )
  • 自动全暂存：无需确认即暂存所有修改文件（
    --auto-stage
    参数）
  • 跳过验证：绕过规范化提交格式检查（
    --skip-validation
    参数）
  • 试运行模式：展示会提交的内容但不实际执行（
    --dry-run
    参数）
  • 提交后推送：提交成功后自动推送到远程仓库（
    --push
    参数）

What This Skill CAN Do

本技能可实现的功能

  • Detect sensitive files before they are committed (regex pattern matching)
  • Validate commit messages against conventional commit format and CLAUDE.md banned patterns
  • Smart-group files by type for logical, atomic commits
  • Generate compliant commit messages from staged changes
  • Verify commits succeeded and working tree is clean post-commit
  • 提交前检测敏感文件（基于正则表达式匹配）
  • 验证提交消息是否符合规范化格式及CLAUDE.md的禁用模式
  • 按类型智能分组文件，实现逻辑化、原子化提交
  • 根据暂存的变更生成合规的提交消息
  • 校验提交是否成功，以及提交后工作区是否干净

What This Skill CANNOT Do

本技能无法实现的功能

  • Resolve merge conflicts (requires contextual code judgment)
  • Perform interactive rebases (incompatible with deterministic workflow)
  • Amend previous commits (use 
    git commit --amend
    directly)
  • Judge code quality (use systematic-code-review skill instead)
  • Auto-resolve conflicting CLAUDE.md rules (requires human judgment)
  • 解决合并冲突（需要上下文代码判断能力）
  • 执行交互式变基（与确定性工作流不兼容）
  • 修正之前的提交（请直接使用
    git commit --amend
    命令）
  • 评判代码质量（请使用systematic-code-review技能）
  • 自动解决CLAUDE.md规则冲突（需要人工判断）

Instructions

操作步骤

Phase 1: VALIDATE

阶段1：VALIDATE（验证）

Goal: Confirm environment is safe for committing.
Step 1: Check working tree state
bash
git status --porcelain
git rev-parse --abbrev-ref HEAD
Verify:
  • Not in merge or rebase state (check for 
    .git/MERGE_HEAD
    or 
    .git/rebase-merge/
    )
  • Not in detached HEAD (if so, warn user to create branch first)
  • Identify current branch name
Step 2: Scan for sensitive files
Check all changed files against sensitive patterns. See 
references/banned-patterns.md
for the full pattern list.
bash
undefined
目标：确认提交环境安全。
步骤1：检查工作区状态
bash
git status --porcelain
git rev-parse --abbrev-ref HEAD
验证内容：
  • 未处于合并或变基状态（检查是否存在
    .git/MERGE_HEAD
    或
    .git/rebase-merge/
    文件）
  • 未处于分离HEAD状态（若处于该状态，提醒用户先创建分支）
  • 识别当前分支名称
步骤2：扫描敏感文件
检查所有变更文件是否匹配敏感模式。完整模式列表请参考
references/banned-patterns.md
。
bash
undefined

TODO: scripts/validate_state.py not yet implemented

TODO: scripts/validate_state.py 尚未实现

Manual alternative: check for sensitive files in staged changes

手动替代方案：检查暂存区中的敏感文件

git diff --cached --name-only | grep -iE '.(env|pem|key)$|credentials|secret|.npmrc|.pypirc'

If sensitive files detected: display them, suggest `.gitignore` additions, and HARD STOP until resolved.

**Step 3: Load CLAUDE.md rules**

Read repository CLAUDE.md to extract:
- Banned commit message patterns
- Conventional commit requirements
- Custom commit rules

If no CLAUDE.md exists, use defaults: ban "Generated with Claude Code" and "Co-Authored-By: Claude".

**Step 4: Check branch state**

If on `main` or `master`: warn user and require explicit confirmation before proceeding.

**Gate**: All checks pass. No sensitive files, no merge/rebase state, CLAUDE.md loaded.
git diff --cached --name-only | grep -iE '.(env|pem|key)$|credentials|secret|.npmrc|.pypirc'

若检测到敏感文件：展示这些文件，建议添加到`.gitignore`，并直接终止流程直至问题解决。

**步骤3：加载CLAUDE.md规则**

读取仓库的CLAUDE.md文件，提取：
- 禁用的提交消息模式
- 规范化提交要求
- 自定义提交规则

若不存在CLAUDE.md文件，则使用默认规则：禁止「Generated with Claude Code」和「Co-Authored-By: Claude」。

**步骤4：检查分支状态**

若当前分支为`main`或`master`：向用户发出警告并要求明确确认后再继续。

**门控要求**：所有检查通过。无敏感文件、无合并/变基操作进行中、已加载CLAUDE.md规则。

Phase 2: STAGE

阶段2：STAGE（暂存）

Goal: Stage files in logical groups for atomic commits.
Step 1: Analyze changes
bash
git status --porcelain
Parse file statuses: Modified (
M
), Added (
A
), Deleted (
D
), Untracked (
??
).
Step 2: Group files by type
Apply staging rules (see 
references/staging-rules.md
for full rules):
CategoryPatternsCommit Prefix
Documentation
*.md
, 
docs/*
docs:
Source code
*.py
, 
*.go
, 
*.js
, 
*.ts
feat:
, 
fix:
, 
refactor:
Configuration
*.yaml
, 
*.json
, 
Makefile
chore:
, 
build:
Tests
*_test.*
, 
tests/*
test:
(or combined with code)
CI/Build
.github/*
, 
Dockerfile
ci:
, 
build:
Step 3: Present staging plan and get confirmation
Show the user which files will be staged and in how many commits. Wait for approval.
Step 4: Execute staging
bash
git add <files>
Re-validate that no sensitive files ended up in the staging area.
Gate: Files staged, no sensitive files in staging area, user confirmed plan.
目标：将文件按逻辑分组暂存，实现原子化提交。
步骤1：分析变更内容
bash
git status --porcelain
解析文件状态：已修改（
M
）、已添加（
A
）、已删除（
D
）、未跟踪（
??
）。
步骤2：按文件类型分组
应用暂存规则（完整规则请参考
references/staging-rules.md
）：
分类匹配模式提交前缀
文档
*.md
, 
docs/*
docs:
源代码
*.py
, 
*.go
, 
*.js
, 
*.ts
feat:
, 
fix:
, 
refactor:
配置文件
*.yaml
, 
*.json
, 
Makefile
chore:
, 
build:
测试文件
*_test.*
, 
tests/*
test:
（或与代码合并）
CI/构建文件
.github/*
, 
Dockerfile
ci:
, 
build:
步骤3：展示暂存计划并获取确认
向用户展示将被暂存的文件及提交分组情况，等待用户确认。
步骤4：执行暂存操作
bash
git add <files>
重新验证暂存区中是否存在敏感文件。
门控要求：文件已暂存、暂存区无敏感文件、用户已确认计划。

Phase 3: COMMIT

阶段3：COMMIT（提交）

Goal: Create a validated commit with a compliant message.
Step 1: Get commit message
Either accept user-provided message or generate one from staged changes.
Step 2: Validate message
bash
undefined
目标：创建经过验证的合规提交。
步骤1：获取提交消息
可接受用户提供的消息，或根据暂存的变更生成消息。
步骤2：验证消息格式
bash
undefined

TODO: scripts/validate_message.py not yet implemented

TODO: scripts/validate_message.py 尚未实现

Manual alternative: validate commit message format

手动替代方案：验证提交消息格式

Check: type prefix exists, no banned patterns, subject line <= 72 chars

检查：是否存在类型前缀、无禁用模式、主题行长度≤72字符


Check:
- Conventional commit format: `<type>[scope]: <description>` (see `references/conventional-commits.md`)
- No banned patterns (see `references/banned-patterns.md`)
- Subject line: lowercase after type, no trailing period, max 72 chars, imperative mood
- Body: separated by blank line, wrapped at 72 chars

If validation fails with CRITICAL (banned pattern): block commit, show suggested revision.
If validation fails with WARNING (line length): show warning, allow user to proceed or revise.

**Step 3: Execute commit**

Use heredoc format to preserve multi-line messages:

```bash
git commit -m "$(cat <<'EOF'
<type>: <subject>

<body>
EOF
)"
Capture commit hash from output for verification.
Gate: Commit message validated and commit executed successfully.

检查内容：
- 规范化提交格式：`<type>[scope]: <description>`（参考`references/conventional-commits.md`）
- 无禁用模式（参考`references/banned-patterns.md`）
- 主题行：类型后为小写、无结尾句号、最长72字符、使用祈使语气
- 正文：与主题行空一行分隔、每行最多72字符

若验证出现严重错误（包含禁用模式）：阻止提交，展示建议的修改方案。
若验证出现警告（行长度问题）：展示警告，允许用户选择继续或修改。

**步骤3：执行提交操作**

使用heredoc格式保留多行消息：

```bash
git commit -m "$(cat <<'EOF'
<type>: <subject>

<body>
EOF
)"
从输出中捕获提交哈希值用于后续校验。
门控要求：提交消息验证通过且提交执行成功。

Phase 4: VERIFY

阶段4：VERIFY（校验）

Goal: Confirm commit succeeded and repository is in expected state.
Step 1: Verify commit exists
bash
git log -1 --format="%H %s"
Confirm commit hash and subject match expectations.
Step 2: Verify clean working tree
bash
git status --porcelain
No staged files should remain (unless user had additional unstaged changes).
Step 3: Verify message persisted
bash
git log -1 --format="%B"
Confirm no banned patterns and format preserved (hooks may modify messages).
Step 4: Display summary
Report: commit hash, branch, files changed, validation results, and suggested next steps (push, create PR).
Gate: All verification passes. Workflow complete.
目标：确认提交成功且仓库处于预期状态。
步骤1：验证提交已记录
bash
git log -1 --format="%H %s"
确认提交哈希值和主题与预期一致。
步骤2：验证工作区干净
bash
git status --porcelain
不应存在残留的暂存文件（除非用户有未暂存的额外变更）。
步骤3：验证消息已持久化
bash
git log -1 --format="%B"
确认消息中无禁用模式且格式保留（钩子可能会修改消息）。
步骤4：展示总结报告
报告内容：提交哈希值、分支、变更文件、验证结果，以及后续操作建议（推送、创建PR）。
门控要求：所有校验通过。工作流完成。

Examples

示例

Example 1: Standard Feature Commit

示例1：标准功能提交

User says: "Commit my changes" Actions:
  1. Validate working tree, scan for sensitive files, load CLAUDE.md (VALIDATE)
  2. Group files by type, present staging plan, user confirms (STAGE)
  3. Generate message like 
    feat: add user authentication
    , validate format (COMMIT)
  4. Verify commit in log, confirm clean tree (VERIFY)
用户指令：「提交我的变更」 操作流程：
  1. 验证工作区、扫描敏感文件、加载CLAUDE.md规则（VALIDATE阶段）
  2. 按类型分组文件、展示暂存计划、用户确认（STAGE阶段）
  3. 生成类似
    feat: add user authentication
    的消息、验证格式（COMMIT阶段）
  4. 验证提交已记录到日志、确认工作区干净（VERIFY阶段）

Example 2: PR Fix Workflow

示例2：PR修复工作流

Internal invocation with explicit message:
bash
skill: git-commit-flow --message "fix: apply PR review feedback"
Runs all 4 phases with the provided message, skipping message generation.
通过内部调用并指定消息：
bash
skill: git-commit-flow --message "fix: apply PR review feedback"
运行全部4个阶段，使用提供的消息，跳过消息生成步骤。

Example 3: Dry Run

示例3：试运行

User says: "Show me what would be committed"
bash
skill: git-commit-flow --dry-run
Runs VALIDATE and STAGE phases, shows commit message preview, but does not execute.
用户指令：「展示会提交的内容」
bash
skill: git-commit-flow --dry-run
运行VALIDATE和STAGE阶段，展示提交消息预览，但不实际执行提交。

Error Handling

错误处理

Error: Sensitive Files Detected

错误：检测到敏感文件

Cause: Files matching sensitive patterns (
.env
, 
*credentials*
, 
*.key
) found in changes. Solution:
  1. Add to 
    .gitignore
    : 
    echo ".env" >> .gitignore
  2. Unstage if already staged: 
    git reset HEAD .env
  3. If already tracked: 
    git rm --cached .env
  4. Re-run validation
原因：变更中包含匹配敏感模式的文件（
.env
、
*credentials*
、
*.key
等）。 解决方案：
  1. 添加到
    .gitignore
    ：
    echo ".env" >> .gitignore
  2. 若已暂存则取消暂存：
    git reset HEAD .env
  3. 若已被跟踪则从仓库中移除：
    git rm --cached .env
  4. 重新运行验证

Error: Banned Pattern in Commit Message

错误：提交消息包含禁用模式

Cause: Message contains prohibited phrases like "Generated with Claude Code" or "Co-Authored-By: Claude". Solution: Remove the banned pattern. Write clean, professional message focused on WHAT changed and WHY. See 
references/banned-patterns.md
for the full list and alternatives.
原因：消息中包含禁止的短语，如「Generated with Claude Code」或「Co-Authored-By: Claude」。 解决方案：移除禁用模式。编写清晰、专业的消息，聚焦于变更内容和变更原因。完整禁用列表及替代方案请参考
references/banned-patterns.md
。

Error: Pre-Commit Hook Failure

错误：提交前钩子执行失败

Cause: Repository pre-commit hook (formatter, linter, tests) rejected the commit. Solution:
  1. Read hook output to identify the issue
  2. Fix the issue (run formatter, fix lint errors)
  3. Re-stage fixed files: 
    git add -u
  4. Create a NEW commit (do not amend - the previous commit did not happen)
原因：仓库的提交前钩子（格式化工具、代码检查器、测试）拒绝了提交。 解决方案： 1.查看钩子输出以定位问题 2.修复问题（运行格式化工具、修正代码检查错误） 3.重新暂存修复后的文件：
git add -u
4.创建新的提交（请勿使用修正提交——之前的提交并未成功）

Error: Merge/Rebase in Progress

错误：合并/变基操作进行中

Cause: Working tree is in an incomplete merge or rebase state. Solution: Complete or abort the merge/rebase (
git merge --abort
or 
git rebase --abort
) before using this skill.
原因：工作区处于未完成的合并或变基状态。 解决方案：完成或中止合并/变基操作（
git merge --abort
或
git rebase --abort
）后再使用本技能。

Anti-Patterns

反模式

Anti-Pattern 1: Committing Without Validation

反模式1：未验证即提交

What it looks like: 
git add . && git commit -m "update files"
Why wrong: Skips sensitive file detection, CLAUDE.md compliance, conventional format checks. Risk of leaking credentials or creating inconsistent history. Do instead: Use this skill to validate all changes before manual commits.
表现：
git add . && git commit -m "update files"
问题：跳过了敏感文件检测、CLAUDE.md合规检查、规范化格式校验。存在泄露凭证或创建不一致提交历史的风险。 正确做法：使用本技能在手动提交前验证所有变更。

Anti-Pattern 2: Using Banned Commit Patterns

反模式2：使用禁用的提交模式

What it looks like: Adding "Generated with Claude Code" or "Co-Authored-By: Claude" to messages. Why wrong: Violates CLAUDE.md standards, adds noise instead of meaningful context. Do instead: Focus on WHAT changed and WHY. No attribution, no emoji unless repo style requires it.
表现：在消息中添加「Generated with Claude Code」或「Co-Authored-By: Claude」。 问题：违反CLAUDE.md标准，添加无意义的内容而非有价值的上下文。 正确做法：聚焦于变更内容和原因。无需添加归属信息，除非仓库风格要求否则不要使用表情符号。

Anti-Pattern 3: Massive Commits with Unrelated Changes

反模式3：包含无关变更的大规模提交

What it looks like: Staging 15 files across 5 features with 
git add .
and message "update". Why wrong: Makes review overwhelming, breaks 
git bisect
, unclear purpose, difficult to revert. Do instead: Use staging groups. One logical change per commit. Each commit independently reviewable.
表现：使用
git add .
暂存15个跨5个功能的文件，消息为「update」。 问题：使代码评审难度大增、破坏
git bisect
功能、提交目的不清晰、回滚困难。 正确做法：使用暂存分组。每次提交对应一个逻辑变更。每个提交应可独立评审。

Anti-Pattern 4: Committing Directly to Main/Master

反模式4：直接提交到Main/Master分支

What it looks like: Making changes on 
main
and pushing directly. Why wrong: Bypasses code review, risks breaking production, makes rollback difficult. Do instead: Create feature branch, commit there, push, create PR.
表现：在
main
分支上修改并直接推送。 问题：绕过了代码评审、可能破坏生产环境、回滚困难。 正确做法：创建功能分支、在分支上提交、推送分支、创建PR。

Anti-Pattern 5: Ignoring Sensitive File Warnings

反模式5：跨分支合并时使用Stash/Pop

What it looks like: Dismissing warnings about 
.env
or credential files and committing anyway. Why wrong: Credentials in git history are permanent. Requires history rewrite and credential rotation to fix. Do instead: IMMEDIATELY add to 
.gitignore
, unstage, and rotate any exposed credentials.
表现：运行
git stash
，切换分支进行合并或变基，然后在原分支上运行
git stash pop
。 问题：暂存的变更基于合并前的状态。合并后执行pop操作可能会将变更静默应用到错误的基础版本上，导致分支漂移。 正确做法：切换分支前提交变更。若必须使用暂存，在pop后使用
git diff
验证工作区差异，确认变更在新的基础版本上仍然合理。 来自learning.db — multi-agent-coordination/stash-pop-branch-drift

Anti-Pattern 6: Stash/Pop Across Branch Merges

参考资料

What it looks like: Running 
git stash
, switching branches to merge or rebase, then 
git stash pop
back on the original branch. Why wrong: Stashed changes were based on the pre-merge state. Popping after a merge can silently apply changes to the wrong base, causing branch drift. Do instead: Commit changes before switching branches. If stash is unavoidable, verify the working tree diff after pop with 
git diff
to confirm changes still make sense against the new base. Graduated from learning.db — multi-agent-coordination/stash-pop-branch-drift
本技能使用以下共享模式：
  • 反合理化 - 防止寻找捷径的合理化借口
  • 校验清单 - 完成前的检查项

References

领域特定反合理化

This skill uses these shared patterns:
  • Anti-Rationalization - Prevents shortcut rationalizations
  • Verification Checklist - Pre-completion checks
合理化借口问题所在要求操作
"快速提交，不需要验证"快速提交可能泄露凭证运行全部4个阶段
"只是文档，跳过敏感文件扫描"文档提交可能包含
.env
文件		验证每一次提交
"我之后再修改消息"之后永远不会做；提交历史是永久的现在就验证消息
"这个小改动直接提交到主分支没问题"小改动也可能引发大问题创建功能分支

Domain-Specific Anti-Rationalization

参考文件

RationalizationWhy It's WrongRequired Action
"Quick commit, no need to validate"Quick commits leak credentialsRun all 4 phases
"It's just docs, skip sensitive scan"Docs commits can include 
.env
files		Validate every commit
"I'll fix the message later"Later never comes; history is permanentValidate message now
"Main branch is fine for this small change"Small changes cause big problemsCreate feature branch
  • ${CLAUDE_SKILL_DIR}/references/conventional-commits.md
    ：类型定义、格式规则、示例、流程图
  • ${CLAUDE_SKILL_DIR}/references/banned-patterns.md
    ：禁止短语、检测规则、替代方案
  • ${CLAUDE_SKILL_DIR}/references/staging-rules.md
    ：文件类型分类、分组策略、自动暂存条件
  • ${CLAUDE_SKILL_DIR}/references/commit-workflow-examples.md
    ：集成示例、高级模式、CI/CD使用方法

Reference Files

—
  • ${CLAUDE_SKILL_DIR}/references/conventional-commits.md
    : Type definitions, format rules, examples, flowchart
  • ${CLAUDE_SKILL_DIR}/references/banned-patterns.md
    : Prohibited phrases, detection rules, alternatives
  • ${CLAUDE_SKILL_DIR}/references/staging-rules.md
    : File type categories, grouping strategies, auto-stage conditions
  • ${CLAUDE_SKILL_DIR}/references/commit-workflow-examples.md
    : Integration examples, advanced patterns, CI/CD usage
—