git-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Workflow

Git 工作流

Standardized Git workflow for commits, pull requests, and releases using conventional commits format and semantic versioning.

基于约定式提交（conventional commits）格式和语义化版本控制（semantic versioning）的标准化Git工作流，适用于提交、拉取请求和版本发布场景。

Prerequisites

前置条件

Tool	Type	Required	Install
git	cli	Yes	`brew install git` or git-scm.com
gh	cli	No	`brew install gh` then `gh auth login` (required for PR and Release)

Do NOT proactively verify these tools on skill load. If a command fails due to a missing tool, directly guide the user through installation and configuration step by step.

工具	类型	是否必需	安装方式
git	命令行工具	是	`brew install git` 或访问 git-scm.com
gh	命令行工具	否	`brew install gh` 后执行 `gh auth login` （创建PR和版本发布时需要）

请勿在技能加载时主动验证这些工具。如果因缺少工具导致命令失败，请直接逐步引导用户完成安装和配置。

When to Use

适用场景

Creating commits: Follow conventional commits with concise, imperative messages
Creating pull requests: Generate PR with clear description and test plan
Creating releases: Update versions, CHANGELOG, tags, and GitHub releases

These workflows can be used independently or together as needed.

创建提交：遵循约定式提交规范，使用简洁的祈使句消息
创建拉取请求（PR）：生成包含清晰描述和测试计划的PR
创建版本发布：更新版本号、CHANGELOG、标签和GitHub版本发布

这些工作流可根据需要独立使用或组合使用。

Platform Detection

平台检测

Check

git remote get-url origin

to select workflow:

Remote URL contains	Commits/Tags/Releases	PR/MR
`github.com`	This skill	This skill ( `gh pr create` )
`codeup.aliyun.com`	This skill	Switch to `yunxiao` skill
`gitlab.com`	This skill	This skill (adapt for GitLab CLI)

通过执行

git remote get-url origin

命令判断远程仓库地址，选择对应的工作流：

远程URL包含	提交/标签/版本发布	PR/MR
`github.com`	使用本技能	使用本技能（ `gh pr create` ）
`codeup.aliyun.com`	使用本技能	切换至 `yunxiao` 技能
`gitlab.com`	使用本技能	使用本技能（适配GitLab CLI）

Quick Reference

快速参考

Commit Format

提交格式

text

type(scope): concise summary

- Optional bullet points (max 3-4)
- Keep short and focused

Types: feat, fix, refactor, docs, test, chore

text

type(scope): 简洁摘要

- 可选项目符号（最多3-4条）
- 保持简短且聚焦

类型：feat（新功能）、fix（修复）、refactor（重构）、docs（文档）、test（测试）、chore（杂项）

Branch Naming

分支命名规范

```
feature/description
```
```
fix/description
```
```
docs/description
```
```
refactor/description
```
```
test/description
```

```
feature/描述内容
```
```
fix/描述内容
```
```
docs/描述内容
```
```
refactor/描述内容
```
```
test/描述内容
```

Release Checklist

版本发布检查清单

Update version in project files
Update CHANGELOG.md
Commit:
```
chore(release): bump version to x.y.z
```

Tag:

git tag v{version} && git push upstream v{version}

Create GitHub release with
```
gh release create
```

更新项目文件中的版本号
更新CHANGELOG.md
提交：
```
chore(release): bump version to x.y.z
```

打标签：

git tag v{version} && git push upstream v{version}

使用
```
gh release create
```
创建GitHub版本发布

Default Behaviors

默认行为

Keep messages concise: Commit messages and PR titles must be short and to the point. Omit filler words. The diff shows "what" — the message explains "why".
No AI signatures: Never include
```
Co-Authored-By: Claude
```
,
```
Generated with Claude Code
```
, or any AI markers in commits or PRs.
Commit always pushes: After commit, always push immediately. Do not ask.
- Has upstream tracking →
```
git push
```
- No upstream tracking →
```
git push -u origin <branch>
```

保持消息简洁：提交消息和PR标题必须简短明了，省略冗余词汇。代码差异展示“做了什么”，消息则解释“为什么这么做”。
无AI签名：请勿在提交或PR中包含
```
Co-Authored-By: Claude
```
、
```
Generated with Claude Code
```
或任何AI标记。
提交后立即推送：提交完成后立即推送，无需询问。
- 已设置上游跟踪 → 执行
```
git push
```
- 未设置上游跟踪 → 执行
```
git push -u origin <branch>
```

Detailed Guides

详细指南

See examples-and-templates.md for commit examples (good/bad), PR body template, and CHANGELOG format.

请查看examples-and-templates.md获取提交示例（正确/错误示范）、PR正文模板和CHANGELOG格式说明。

Validation

验证方式

Use

scripts/validate_commit.py

to validate commit messages:

bash

python3 scripts/validate_commit.py "feat(auth): add OAuth2 support"
python3 scripts/validate_commit.py --file .git/COMMIT_EDITMSG

The validator checks:

Conventional commits format
Subject line length (< 72 chars)
Imperative mood usage
Absence of AI-generated markers
Body format and bullet point count

使用

scripts/validate_commit.py

脚本验证提交消息格式：

bash

python3 scripts/validate_commit.py "feat(auth): add OAuth2 support"
python3 scripts/validate_commit.py --file .git/COMMIT_EDITMSG

验证脚本会检查以下内容：

约定式提交格式是否合规
主题行长度（<72字符）
是否使用祈使语气
是否存在AI生成标记
正文格式和项目符号数量

Common Workflows

常见工作流

Commit (default: commit + push)

提交（默认：提交 + 推送）

bash

git add <files>
git commit -m "feat(component): add new feature" && git push

bash

git add <files>
git commit -m "feat(component): add new feature" && git push

Pull Request

拉取请求（PR）

bash

git checkout -b feature/new-feature

bash

git checkout -b feature/new-feature

... make changes, commit (auto-pushes per default behavior) ...

... 进行代码修改，提交（按默认行为自动推送） ...

gh pr create --title "feat(component): add new feature" --body "..."

undefined

gh pr create --title "feat(component): add new feature" --body "..."

undefined

Release

版本发布

bash

undefined

bash

undefined

Update version files + CHANGELOG.md

更新版本文件和CHANGELOG.md

git add . git commit -m "chore(release): bump version to 1.2.0" && git push git tag v1.2.0 && git push upstream v1.2.0 gh release create v1.2.0 -R owner/repo --title "v1.2.0" --notes "..."

undefined

git add . git commit -m "chore(release): bump version to 1.2.0" && git push git tag v1.2.0 && git push upstream v1.2.0 gh release create v1.2.0 -R owner/repo --title "v1.2.0" --notes "..."

undefined

Common Issues

常见问题

Issue	Cause	Fix
Subject line > 72 chars	Description too long	Shorten summary, put details in body
Multiple types in one commit	Scope too large	Split into single-purpose commits
Merge commits appear	Used merge	Use `git pull --rebase`
Validator script errors	Format mismatch	Check type(scope): format

问题	原因	解决方法
主题行长度超过72字符	描述过于冗长	精简摘要，将细节放在正文中
单个提交包含多种类型	范围过大	拆分为单一目的的提交
出现合并提交	使用了合并操作	使用 `git pull --rebase`
验证脚本报错	格式不匹配	检查是否符合 `type(scope):` 格式