semantic-git

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Semantic Git

语义化Git

Manage Git commits using conventional commit format with atomic commits and concise messages.

This skill is zagi-aware and is designed to work well with AI IDEs (Cursor, etc.)

使用规范提交格式、原子提交和简洁消息来管理Git提交。

此技能支持zagi，专为AI IDE（如Cursor等）设计。

Tooling

工具选择

Preferred:
```
zagi
```
(a better git interface for agents).
- Assume zagi is installed if:
  - ```
  git
```
  is aliased to zagi in the shell or
- a
```
  zagi
```
  binary is available.
- When in doubt, treat
```
git
```
  as if it may be zagi-compatible and avoid using exotic flags.
- Even when zagi is available, generate plain
  git
  commands and let any
```
git
```
  →
```
zagi
```
  integration handle them.
Fallback: plain
```
git
```
when zagi is not available.

首选工具：
```
zagi
```
（面向Agent的更优Git界面）。
- 在以下情况下假设已安装zagi：
  - shell中
```
git
```
    被别名为zagi，或者
  - 存在
```
zagi
```
    可执行文件。
- 若不确定，将
```
git
```
  视为兼容zagi的工具，避免使用特殊标志。
- 即使已安装zagi，也需生成纯
  git
  命令，由
```
git
```
  →
```
zagi
```
  的集成机制自动处理。
备选方案：当zagi不可用时使用原生
```
git
```
。

When to Use

使用场景

Committing changes to git
Staging files for commit
Creating commit messages
Managing atomic commits
Before pushing changes

提交Git变更
暂存文件以准备提交
生成提交消息
管理原子提交
推送变更前的准备

Core Principles

核心原则

Atomic commits: Stage and commit related changes together. Tests go with implementation code.
User confirmation: Always confirm with user before committing and before moving to the next commit.
Conventional format: Use conventional commit message format (feat, fix, etc.) unless directed otherwise.
Concise messages: Keep messages brief and to the point. Omit description unless change is complicated.
Command transparency: Always show the exact
```
git
```
commands that will be run (which may be handled by zagi via alias/wrapper), and ask whether the user wants:
- to run them manually, or
- to have the agent run them.

原子提交：将相关变更（如实现代码与测试）一起暂存并提交。
用户确认：提交前及进行下一次提交前，始终需获得用户确认。
规范格式：除非另有指示，否则使用规范提交消息格式（feat、fix等类型）。
简洁消息：消息需简短明了，仅在变更复杂时添加描述。
命令透明：始终展示即将执行的完整
```
git
```
命令（可能通过别名或包装器如zagi处理），并询问用户希望：
- 手动执行命令，或
- 由Agent执行命令。

Commit Message Format

提交消息格式

<type>[optional scope]: <subject>

[optional body]

[optional footer(s)]

<type>[可选 scope]: <subject>

[可选 body]

[可选 footer(s)]

Types

类型说明

```
feat
```
: A new feature
```
fix
```
: A bug fix
```
docs
```
: Documentation only changes
```
style
```
: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc.)
```
refactor
```
: A code change that neither fixes a bug nor adds a feature
```
perf
```
: A code change that improves performance
```
test
```
: Adding missing tests or correcting existing tests
```
build
```
: Changes that affect the build system or external dependencies
```
ci
```
: Changes to CI configuration files and scripts
```
chore
```
: Maintenance tasks (updating build tasks, dependencies, etc.; no production code change)
```
revert
```
: Revert a previous commit

```
feat
```
: 新增功能
```
fix
```
: 修复Bug
```
docs
```
: 仅修改文档
```
style
```
: 不影响代码逻辑的变更（如空白字符、格式调整、缺失分号等）
```
refactor
```
: 既非修复Bug也非新增功能的代码变更
```
perf
```
: 性能优化的代码变更
```
test
```
: 添加缺失测试或修正现有测试
```
build
```
: 影响构建系统或外部依赖的变更
```
ci
```
: 修改CI配置文件或脚本
```
chore
```
: 维护任务（如更新构建任务、依赖等；不修改生产代码）
```
revert
```
: 回滚之前的提交

Breaking Changes

破坏性变更

Use

after the type/scope to indicate breaking changes:

```
feat!: add new API
```
```
fix(api)!: change response format
```

在类型/scope后添加

表示破坏性变更：

```
feat!: add new API
```
```
fix(api)!: change response format
```

Subject Line

主题行规则

Use imperative mood: "add feature" not "added feature" or "adds feature"
First letter lowercase (unless starting with proper noun)
No period at the end
Keep under 72 characters when possible

使用祈使语气：如“add feature”而非“added feature”或“adds feature”
首字母小写（专有名词开头除外）
结尾不加句号
尽可能控制在72字符以内

Body and Footer

正文与页脚

Omit body unless change is complicated or requires explanation
When needed, be concise and reference issues, PRs, or documentation
Use footer for breaking changes:
```
BREAKING CHANGE: <description>
```

仅在变更复杂或需要解释时添加正文
若需添加正文，需简洁明了，并可引用Issue、PR或文档
破坏性变更需在页脚标注：
```
BREAKING CHANGE: <描述>
```

Workflow

工作流程

Implement atomic change: Code + tests together.
- Use
```
test:
```
  for test-only changes.
Run CI checks: Verify types, tests, and linting pass before staging.
- Prefer a single CI command if it exists (e.g.,
```
pnpm ci
```
  ,
```
npm run ci
```
  ,
```
just ci
```
  ).
- If no CI command, run checks individually (typecheck, test, lint).
- If any check fails, stop and report – do not proceed.
Stage atomic changes: Group related files together (implementation + tests).
Suggest commit message: Generate a conventional commit message based on changes.
Generate commands:
- Construct explicit shell commands using
```
git
```
  (which may be an alias or wrapper such as zagi), for example:
  bash
```
git add path/to/file1 path/to/file2
GIT_AUTHOR_DATE="YYYY-MM-DD HH:MM:SS" \
GIT_COMMITTER_DATE="YYYY-MM-DD HH:MM:SS" \
git commit -m "feat: add feature"
```
- Always print these commands to the user in order.
Ask for execution preference:
- Ask the user whether they want:
  - to copy-paste and run the commands themselves, or
  - to have the agent run them.
- Only execute commands after explicit user approval.
Commit:
- When executing, run exactly the printed commands.
- Respect any user instructions about backdating timestamps or additional flags.
Next commit:
- Before staging the next set of changes, confirm with the user that the previous commit is complete and understood.

实现原子变更：代码与测试需同步完成。
- 仅修改测试时使用
```
test:
```
  类型。
运行CI检查：暂存前需验证类型检查、测试与代码规范均通过。
- 优先使用单一CI命令（如
```
pnpm ci
```
  、
```
npm run ci
```
  、
```
just ci
```
  ）。
- 若无CI命令，则单独运行各项检查（类型检查、测试、代码规范）。
- 若任何检查失败，需停止操作并报告，不得继续。
暂存原子变更：将相关文件分组暂存（实现代码+测试）。
建议提交消息：根据变更内容生成符合规范的提交消息。

生成命令：

使用

git

构建明确的Shell命令（可能是别名或包装器如zagi），例如：

bash

git add path/to/file1 path/to/file2
GIT_AUTHOR_DATE="YYYY-MM-DD HH:MM:SS" \
GIT_COMMITTER_DATE="YYYY-MM-DD HH:MM:SS" \
git commit -m "feat: add feature"

必须按顺序将这些命令展示给用户。

询问执行方式：
- 询问用户希望：
  - 复制命令并手动执行，或
  - 由Agent执行命令。
- 仅在获得用户明确批准后执行命令。
执行提交：
- 执行时需严格按照展示的命令运行。
- 遵循用户关于回溯时间戳或添加额外标志的指示。
下一次提交：
- 在暂存下一组变更前，需确认用户已完成并理解上一次提交。

Automation Mode

自动化模式

If user requests "continue to X" or "automate until X":

Proceed with atomic commits automatically, but still print commands.
For each commit:
- Show the staging and commit commands.
- Optionally execute them automatically, as per the user’s automation request.
Resume asking for confirmation when X is reached.
X can be: specific file, feature completion, test passing, etc.

若用户要求“继续执行至X”或“自动执行至X”：

自动进行原子提交，但仍需展示命令。
对于每一次提交：
- 展示暂存与提交命令。
- 根据用户的自动化请求，可选择自动执行命令。
当达到X时，恢复询问用户确认。
X可以是：特定文件、功能完成、测试通过等。

Stop and Ask Protocols

停止并询问的场景

Stop and ask user before:

Adding type ignores (
```
@ts-ignore
```
,
```
# type: ignore
```
, etc.).
Adding suppressions (ESLint disable, pylint disable, etc.).
Using
```
any
```
type or similar type escapes.
When uncertain how to proceed with implementation.
When requirements are unclear.
When a destructive git operation is proposed (
```
reset --hard
```
,
```
checkout .
```
,
```
clean -f
```
,
```
push --force
```
); prefer safer alternatives and explain the risks.

在以下场景下需停止操作并询问用户：

添加类型忽略（
```
@ts-ignore
```
、
```
# type: ignore
```
等）。
添加抑制规则（ESLint disable、pylint disable等）。
使用
```
any
```
类型或类似的类型规避手段。
不确定如何继续实现时。
需求不明确时。
拟执行破坏性Git操作（
```
reset --hard
```
、
```
checkout .
```
、
```
clean -f
```
、
```
push --force
```
）；优先选择更安全的替代方案，并解释风险。

Examples

示例

Simple feature or behaviour change:

feat: add user authentication

Feature with scope:

feat(api): add user endpoint

Bug fix:

fix: resolve memory leak in cache

Breaking change:

feat!: migrate to new API version

Test-only change:

test: improve unit tests for auth service

Refactor (no behavior change):

refactor: extract validation logic into separate function

Complex change (with body):

feat(api): add pagination support

Implements cursor-based pagination for large datasets.
See docs/api/pagination.md for details.

简单功能或行为变更：

feat: add user authentication

带scope的功能变更：

feat(api): add user endpoint

Bug修复：

fix: resolve memory leak in cache

破坏性变更：

feat!: migrate to new API version

仅测试变更：

test: improve unit tests for auth service

重构（无行为变更）：

refactor: extract validation logic into separate function

复杂变更（含正文）：

feat(api): add pagination support

Implements cursor-based pagination for large datasets.
See docs/api/pagination.md for details.

References

参考资料

For detailed guidance, see:

```
references/conventional-commits.md
```
– Commit format and examples
```
references/ci-verification.md
```
– CI check patterns and verification
```
references/co-authors.md
```
– Handling Co-Authored-By trailers and zagi co-author stripping

如需详细指导，请参阅：

```
references/conventional-commits.md
```
– 提交格式与示例
```
references/ci-verification.md
```
– CI检查模式与验证
```
references/co-authors.md
```
– 处理Co-Authored-By标记与zagi的合著者剥离功能