git-github

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git and GitHub Workflow Skill

Git与GitHub工作流技能指南

Comprehensive guide for Git version control and GitHub collaboration patterns.

Git版本控制与GitHub协作模式的全面指南。

When This Activates

触发场景

Creating commits or branches
Opening or reviewing pull requests
Managing GitHub issues
Using the gh CLI
Keywords: "git", "github", "commit", "branch", "pr", "pull request", "merge", "issue"

创建提交或分支
创建或审核拉取请求（PR）
管理GitHub Issues
使用gh CLI
关键词："git"、"github"、"commit"、"branch"、"pr"、"pull request"、"merge"、"issue"

Conventional Commits

Conventional Commits（规范提交）

All commit messages follow the conventional commits specification:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

所有提交消息需遵循Conventional Commits规范：

<type>(<scope>): <description>

[可选正文]

[可选页脚]

Types

类型

Type	When to Use
`feat`	New feature or capability
`fix`	Bug fix
`docs`	Documentation only changes
`style`	Formatting, missing semicolons, etc.
`refactor`	Code change that neither fixes a bug nor adds a feature
`perf`	Performance improvement
`test`	Adding or correcting tests
`chore`	Build process, auxiliary tools, or maintenance
`ci`	CI/CD configuration changes

类型	使用场景
`feat`	新增功能或能力
`fix`	修复Bug
`docs`	仅修改文档
`style`	代码格式化、缺失分号等
`refactor`	既不修复Bug也不新增功能的代码变更
`perf`	性能优化
`test`	添加或修正测试
`chore`	构建流程、辅助工具或维护工作
`ci`	CI/CD配置变更

Examples

示例

bash

feat(auth): add JWT token refresh endpoint
fix(api): handle null response from upstream service
docs: update API reference for v2 endpoints
refactor(db): extract query builder into separate module
test(auth): add integration tests for OAuth flow
chore: upgrade dependencies to latest versions

bash

feat(auth): add JWT token refresh endpoint
fix(api): handle null response from upstream service
docs: update API reference for v2 endpoints
refactor(db): extract query builder into separate module
test(auth): add integration tests for OAuth flow
chore: upgrade dependencies to latest versions

Breaking Changes

破坏性变更

Use

after type or add

BREAKING CHANGE:

footer:

bash

feat(api)!: change response format from XML to JSON

在类型后添加

或在页脚中添加

BREAKING CHANGE:

：

bash

feat(api)!: change response format from XML to JSON

Branch Naming Conventions

分支命名规范

<type>/<issue-number>-<short-description>

<type>/<issue-number>-<short-description>

Patterns

模式

Pattern	Example
Feature	`feat/123-add-user-auth`
Bug fix	`fix/456-null-pointer-crash`
Docs	`docs/789-update-api-reference`
Refactor	`refactor/101-extract-helpers`

模式	示例
功能分支	`feat/123-add-user-auth`
Bug修复分支	`fix/456-null-pointer-crash`
文档分支	`docs/789-update-api-reference`
重构分支	`refactor/101-extract-helpers`

Rules

规则

Use lowercase with hyphens (no underscores or spaces)
Include issue number when applicable
Keep descriptions under 5 words
Delete branches after merging

使用小写字母，连字符分隔（不使用下划线或空格）
适用时包含Issue编号
描述控制在5个单词以内
合并后删除分支

PR Workflow with gh CLI

基于gh CLI的PR工作流

Creating Pull Requests

创建拉取请求

bash

undefined

bash

undefined

Create PR with title and body

创建带标题和正文的PR

gh pr create --title "feat: add user authentication" --body "$(cat <<'EOF'

Summary

摘要

Add JWT-based authentication
Implement login/logout endpoints

添加基于JWT的认证功能
实现登录/登出端点

Test plan

测试计划

Unit tests for token generation
Integration tests for auth flow EOF )"

令牌生成单元测试
认证流程集成测试 EOF )"

Create draft PR

创建草稿PR

gh pr create --draft --title "wip: refactor database layer"

Create PR targeting specific base branch

创建针对特定基准分支的PR

gh pr create --base develop --title "feat: new feature"

undefined

gh pr create --base develop --title "feat: new feature"

undefined

Reviewing Pull Requests

审核拉取请求

bash

undefined

bash

undefined

List open PRs

列出所有开放的PR

gh pr list

View PR details

查看PR详情

gh pr view 123

Check out PR locally

在本地检出PR

gh pr checkout 123

Approve PR

批准PR

gh pr review 123 --approve

Request changes

请求修改

gh pr review 123 --request-changes --body "Please fix the error handling"

gh pr review 123 --request-changes --body "请修复错误处理逻辑"

Merge PR

合并PR

gh pr merge 123 --squash --delete-branch

undefined

gh pr merge 123 --squash --delete-branch

undefined

PR Best Practices

PR最佳实践

Keep PRs small - Under 400 lines changed when possible
One concern per PR - Don't mix features with refactors
Write descriptive titles - Use conventional commit format
Include test plan - Checklist of what to verify
Link issues - Use "Closes #123" in body

PR保持精简 - 尽可能控制变更行数在400行以内
单一关注点 - 不要混合功能开发与代码重构
标题描述清晰 - 使用规范提交格式
包含测试计划 - 列出需要验证的事项清单
关联Issues - 在正文中使用"Closes #123"

Issue Management

Issue管理

Creating Issues

创建Issues

bash

undefined

bash

undefined

Create issue with title and body

创建带标题和正文的Issue

gh issue create --title "Bug: login fails on Safari" --body "Steps to reproduce..."

gh issue create --title "Bug: login fails on Safari" --body "复现步骤..."

Create with labels

创建带标签的Issue

gh issue create --title "feat: dark mode" --label "enhancement,ui"

Create with assignee

创建指定负责人的Issue

gh issue create --title "fix: memory leak" --assignee "@me"

undefined

gh issue create --title "fix: memory leak" --assignee "@me"

undefined

Issue Templates

Issue模板

Use labels to categorize:

Label	Color	Purpose
`bug`	red	Something broken
`enhancement`	blue	New feature request
`documentation`	green	Docs improvement
`good first issue`	purple	Beginner friendly
`priority: high`	orange	Needs immediate attention

使用标签进行分类：

标签	颜色	用途
`bug`	红色	功能故障
`enhancement`	蓝色	新功能请求
`documentation`	绿色	文档改进
`good first issue`	紫色	适合新手的任务
`priority: high`	橙色	需要立即处理

Linking Issues to PRs

关联Issues与PR

bash

undefined

bash

undefined

In PR body

在PR正文中添加

Closes #123 Fixes #456 Resolves #789

---

Closes #123 Fixes #456 Resolves #789

---

Git Hooks Best Practices

Git Hooks最佳实践

Pre-commit

Pre-commit（提交前钩子）

bash

undefined

bash

undefined

Format code

代码格式化检查

black --check src/ isort --check src/

Lint

代码 lint 检查

flake8 src/

Check for secrets

敏感信息扫描

detect-secrets scan

undefined

detect-secrets scan

undefined

Pre-push

Pre-push（推送前钩子）

bash

undefined

bash

undefined

Run tests

运行测试

pytest tests/ -x --timeout=60

Type check

类型检查

mypy src/

undefined

mypy src/

undefined

Commit-msg

Commit-msg（提交消息钩子）

bash

undefined

bash

undefined

Validate conventional commit format

验证规范提交格式

pattern="^(feat|fix|docs|style|refactor|perf|test|chore|ci)((.+))?!?: .{1,72}" if ! echo "$1" | grep -qE "$pattern"; then echo "Invalid commit message format" exit 1 fi

---

pattern="^(feat|fix|docs|style|refactor|perf|test|chore|ci)((.+))?!?: .{1,72}" if ! echo "$1" | grep -qE "$pattern"; then echo "Invalid commit message format" exit 1 fi

---

Common Git Operations

常见Git操作

Stashing Changes

暂存变更

bash

git stash push -m "wip: authentication changes"
git stash list
git stash pop

bash

git stash push -m "wip: authentication changes"
git stash list
git stash pop

Interactive Rebase (cleanup before PR)

交互式变基（PR前清理提交）

bash

git rebase -i HEAD~3  # Squash last 3 commits

bash

git rebase -i HEAD~3  # 合并最近3次提交

Cherry-picking

拣选提交

bash

git cherry-pick abc1234  # Apply specific commit

bash

git cherry-pick abc1234  # 应用指定提交

Resolving Conflicts

解决冲突

bash

git merge main           # Trigger merge

bash

git merge main           # 触发合并

Fix conflicts in editor

在编辑器中修复冲突

git add . git commit # Complete merge

---

git add . git commit # 完成合并

---

Key Takeaways

核心要点

Conventional commits - Always use type(scope): description format
Branch naming - type/issue-description pattern
Small PRs - Under 400 lines, one concern each
gh CLI - Use for all GitHub operations
Link issues - Always connect PRs to issues
Git hooks - Automate quality checks
Delete merged branches - Keep repository clean

Conventional Commits - 始终使用
```
type(scope): description
```
格式
分支命名 - 遵循
```
type/issue-description
```
模式
PR精简 - 变更行数控制在400行以内，单一关注点
gh CLI - 所有GitHub操作均使用gh CLI完成
关联Issues - PR必须关联对应的Issues
Git Hooks - 自动化质量检查
删除已合并分支 - 保持仓库整洁

Hard Rules

硬性规则

FORBIDDEN:

Force-pushing to main/master without explicit approval
Committing secrets, API keys, or credentials (use
```
.env
```
files)
Merge commits with failing CI checks
PRs without linked issues or description

REQUIRED:

All PRs MUST have a description explaining the "why"
Branch names MUST follow
```
type/issue-description
```
pattern
Commits MUST use conventional commit format (
```
feat:
```
,
```
fix:
```
,
```
docs:
```
, etc.)
All PRs MUST pass CI before merge

禁止操作：

未经明确批准强制推送到main/master分支
提交密钥、API密钥或凭证（使用
```
.env
```
文件）
合并CI检查失败的提交
未关联Issues或无描述的PR

必须操作：

所有PR必须包含说明变更原因的描述
分支名称必须遵循
```
type/issue-description
```
模式
提交必须使用规范提交格式（
```
feat:
```
、
```
fix:
```
、
```
docs:
```
等）
所有PR必须通过CI检查后才能合并