writing-and-creating-git-commits

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create a semantic commit to accomodate user request.

创建语义化提交以满足用户需求。

Soft Validation

软校验

If any of these checks fail, check with the user before proceeding.

WARN_ON_DEFAULTBRANCH: !

[$(git branch --show-current) = $(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name)] && echo 1 || echo 0

should equal 0

WARN_MERGECONFLICTS: !
```
git ls-files -u | wc -l
```
should equal 0

WARN_INVALIDBRANCHNAME: !

git branch --show-current

should match

^(feat|fix|docs|style|refactor|perf|test|chore)\/[a-z0-9\-]+$

(if not on default branch)

如果以下任何检查未通过，请先与用户确认后再继续。

WARN_ON_DEFAULTBRANCH: !

[$(git branch --show-current) = $(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name)] && echo 1 || echo 0

应等于0

WARN_MERGECONFLICTS: !
```
git ls-files -u | wc -l
```
应等于0

WARN_INVALIDBRANCHNAME: !

git branch --show-current

应匹配

^(feat|fix|docs|style|refactor|perf|test|chore)\/[a-z0-9\-]+$

（若当前不在默认分支）

Hard Validation

硬校验

If any of these checks fail, fix the issue before proceeding. or Exit if human intervention is required.

on default branch, but it needs to be fastforwarded from remote.
uncommitted merge conflicts detected. Please resolve them before committing.

如果以下任何检查未通过，请先修复问题后再继续；若需要人工干预则退出流程。

当前在默认分支，但需要从远程仓库快进更新。
检测到未提交的合并冲突，请在提交前解决。

Setup

设置步骤

Ensure git is installed and configured with user name and email.

确保已安装git，并配置好用户名和邮箱。

Execution Process

执行流程

Analyse
Prepare
Commit
Sync

分析
准备
提交
同步

1. Analyse Changes

1. 分析变更

Assess current state:
bash
```
git status --porcelain
git diff --stat
git diff --cached --stat
```
- Identify all modified, added, and deleted files
- Check for any staged changes already in place
- Note any untracked files that should be included
Analyze changes by file:
bash
```
git diff
git diff --cached
```
- Review the actual content of each change
- Understand what each modification accomplishes
- Identify related changes that belong together

评估当前状态:
bash
```
git status --porcelain
git diff --stat
git diff --cached --stat
```
- 识别所有已修改、新增和删除的文件
- 检查是否已有暂存的变更
- 记录需要纳入提交的未跟踪文件
按文件分析变更:
bash
```
git diff
git diff --cached
```
- 查看每个变更的实际内容
- 理解每项修改的作用
- 识别属于同一逻辑单元的相关变更

2. Prepare Changes

2. 准备变更

Group changes into logical commits:
- Each commit should represent ONE logical change (feature, fix, refactor, etc.)
- Related files should be committed together
- Avoid mixing unrelated changes in a single commit
- Order commits logically (dependencies first, then dependents)

将变更分组为逻辑提交:
- 每个提交应代表一个逻辑变更（功能、修复、重构等）
- 相关文件应一起提交
- 避免在单个提交中混合无关变更
- 按逻辑顺序排列提交（先提交依赖项，再提交依赖它的变更）

3. Commit Changes

3. 提交变更

Create atomic commits: For each logical group:

bash

git add <specific-files>
git commit -m "<type>: <brief description>"

创建原子提交: 针对每个逻辑组执行：

bash

git add <specific-files>
git commit -m "<type>: <brief description>"

4. Push Process

4. 推送流程

determine default branch with the gh cli tool
fast forward the default branch from remote: ie:
```
git fetch origin master:master
```
rebase the current branch onto the default branch: ie:
```
git rebase master
```
push the current branch to remote: ie:
```
git push origin HEAD --force-with-lease
```

使用gh cli工具确定默认分支
从远程仓库快进更新默认分支：例如
```
git fetch origin master:master
```
将当前分支变基到默认分支：例如
```
git rebase master
```
将当前分支推送到远程仓库：例如
```
git push origin HEAD --force-with-lease
```

Guidance: Commit Message Writing

提交信息撰写指南

Use the

skills_superpowers_writing_git_commits

skill to guide you in writing great commit messages and body content following the Conventional Commits specification.

Otherwise:

Use conventional commit prefixes:

```
feat:
```
- New feature, functionality.
```
fix:
```
- Bug fix or refactoring.
```
docs:
```
- Documentation changes
```
style:
```
- Formatting, whitespace (no code change)
```
test:
```
- Adding or updating tests
```
chore:
```
- Maintenance tasks, dependencies, config

Commit Message format:

1st line:
```
<type>(scope): <subject>
```
Blank line
Body: Detailed explanation of what and why (wrap at 72 chars)
- Keep subject line under 72 characters
- Use imperative mood ("add" not "added")
- Be specific but concise
- No period at the end of subject line

Examples:

```
feat: add user authentication endpoint
```

fix(config): resolve null pointer in config parser

feat(scope): extract validation logic to separate module

docs(apiv2): update API documentation for v2 endpoints

chore: update dependencies to latest versions

使用

skills_superpowers_writing_git_commits

技能，遵循Conventional Commits规范撰写优质的提交信息和正文内容。

若未使用该技能，请遵循以下规则：

使用规范的提交前缀：

```
feat:
```
- 新功能、新特性
```
fix:
```
- Bug修复或重构
```
docs:
```
- 文档变更
```
style:
```
- 格式调整、空白字符修改（无代码逻辑变更）
```
test:
```
- 添加或更新测试
```
chore:
```
- 维护任务、依赖更新、配置调整

提交信息格式：

第一行：
```
<type>(scope): <subject>
```
空一行
正文：详细说明变更内容和原因（每行不超过72字符）
- 主题行长度不超过72字符
- 使用祈使语气（如“add”而非“added”）
- 具体且简洁
- 主题行末尾不加句号

示例：

```
feat: add user authentication endpoint
```

fix(config): resolve null pointer in config parser

feat(scope): extract validation logic to separate module

docs(apiv2): update API documentation for v2 endpoints

chore: update dependencies to latest versions

Content Guidelines

内容准则

Use direct, factual commit messages
Avoid vague messages ("fix bug", "update code", "misc changes")
No emojis unless project convention requires them
Focus on WHAT changed and WHY (briefly)
Group related changes even if in different files

使用直接、真实的提交信息
避免模糊表述（如“修复bug”、“更新代码”、“杂项变更”）
除非项目有约定，否则不要使用表情符号
重点说明变更内容和原因（简洁表述）
即使变更涉及不同文件，也要将相关变更分组提交