Git Skills & Best Practices

Git技能与最佳实践

Git workflow standards, commit conventions, hooks, and pull request practices.

Git工作流标准、提交规范、钩子以及拉取请求实践。

Git Workflow

Git工作流

Conventional Commits

MUST use Conventional Commits format - this is a strict requirement. Follow the Conventional Commits specification:

Format:

<type>[optional scope]: <description>

[optional body]

[optional 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
```
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
```
chore
```
: Changes to the build process or auxiliary tools

Examples:

feat(auth): add user login functionality
fix(api): resolve race condition in data fetching
docs: update README with setup instructions

必须使用Conventional Commits格式——这是硬性要求。遵循Conventional Commits规范:

格式:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

类型:

```
feat
```
: 新增功能
```
fix
```
: 修复bug
```
docs
```
: 仅修改文档
```
style
```
: 不影响代码含义的修改（如格式调整）
```
refactor
```
: 既不是修复bug也不是新增功能的代码变更
```
perf
```
: 提升性能的代码变更
```
test
```
: 添加缺失的测试或修正现有测试
```
chore
```
: 构建流程或辅助工具的变更

示例:

feat(auth): add user login functionality
fix(api): resolve race condition in data fetching
docs: update README with setup instructions

.gitignore

Include standard exclusions for React/React Native projects:

Essential entries:

undefined

包含React/React Native项目的标准排除项:

核心条目:

undefined

Environment variables

.env .env.local .env.*.local

Dependencies

node_modules/ .pnp .pnp.js

Build outputs

dist/ build/ .next/ out/

Testing

coverage/ .nyc_output/

IDE

.vscode/ .idea/ *.swp *.swo *~

OS

.DS_Store Thumbs.db

Logs

.log npm-debug.log yarn-debug.log* yarn-error.log* lerna-debug.log* pnpm-debug.log*

pnpm

.pnpm-store/

Misc

.cache/ .temp/ .turbo/

---

.cache/ .temp/ .turbo/

---

Git Hooks

Git钩子

Lefthook Integration

Lefthook集成

PREFER using Lefthook for managing git hooks (guideline). Other tools are acceptable if they meet the strict hook requirements below.

Configuration (
lefthook.yml
):

yaml

pre-commit:
  parallel: true
  commands:
    lint:
      run: pnpm run lint
      stage_fixed: true
    format:
      run: pnpm run format:check
      stage_fixed: true
    test:
      run: pnpm run test:ci
      stage_fixed: true

pre-push:
  parallel: true
  commands:
    test:
      run: pnpm run test
    typecheck:
      run: pnpm run typecheck

Pre-commit hooks (Strict Requirements):

MUST run linting checks
MUST run formatting checks
MUST run unit tests
Auto-fix issues when possible

Pre-push hooks (Strict Requirements):

MUST run full test suite
MUST run TypeScript type checking (
```
tsc
```
)
MUST prevent pushing if checks fail

优先推荐使用Lefthook管理Git钩子（指导原则）。如果其他工具能满足以下严格的钩子要求，也可以使用。

配置文件 (
lefthook.yml
):

yaml

pre-commit:
  parallel: true
  commands:
    lint:
      run: pnpm run lint
      stage_fixed: true
    format:
      run: pnpm run format:check
      stage_fixed: true
    test:
      run: pnpm run test:ci
      stage_fixed: true

pre-push:
  parallel: true
  commands:
    test:
      run: pnpm run test
    typecheck:
      run: pnpm run typecheck

提交前钩子（硬性要求）:

必须运行代码检查
必须运行格式检查
必须运行单元测试
尽可能自动修复问题

推送前钩子（硬性要求）:

必须运行完整测试套件
必须运行TypeScript类型检查 (
```
tsc
```
)
必须在检查不通过时阻止推送

Pull Request Templates

拉取请求模板

Create

.github/pull_request_template.md

with the following structure:

markdown

undefined

创建

.github/pull_request_template.md

文件，结构如下:

markdown

undefined

Overview

Solution

Screenshots

Ticket

Tested On

Additional Notes

---

---

GitHub CLI (gh) Integration

GitHub CLI (gh) 集成

The GitHub CLI (

gh

) enables AI agents to interact with GitHub repositories programmatically, automating common Git and GitHub workflows.

GitHub CLI（

gh

）允许AI Agent以编程方式与GitHub仓库交互，自动化常见的Git和GitHub工作流。

Authentication

身份验证

Setup:

bash

undefined

设置步骤:

bash

undefined

Login to GitHub

gh auth login

Check authentication status

gh auth status

Refresh authentication token

gh auth refresh


**For AI Agents:**
- Use `gh auth token` to retrieve the authentication token for API calls
- Configure authentication before performing any GitHub operations
- Use `gh auth setup-git` to configure Git credentials automatically

gh auth refresh


**针对AI Agent:**
- 使用`gh auth token`获取API调用所需的身份验证令牌
- 在执行任何GitHub操作前配置身份验证
- 使用`gh auth setup-git`自动配置Git凭据

Pull Request Management

拉取请求管理

Create Pull Requests:

bash

undefined

创建拉取请求:

bash

undefined

Create a PR interactively

gh pr create

Create a PR with title and body

gh pr create --title "feat: add user authentication" --body "Implements OAuth2 login flow"

Create a PR from current branch to main

gh pr create --base main --head feature/auth --title "feat: add authentication"

Create a draft PR

gh pr create --draft


**View and Manage PRs:**
```bash

gh pr create --draft


**查看和管理拉取请求:**
```bash

List open PRs

gh pr list

View PR details

gh pr view <number>

View PR diff

gh pr diff <number>

Checkout PR locally

gh pr checkout <number>

Review PR status and checks

gh pr checks <number>

Comment on PR

gh pr comment <number> --body "LGTM! Great work."

Approve PR

gh pr review <number> --approve

Merge PR

gh pr merge <number> --squash gh pr merge <number> --merge gh pr merge <number> --rebase


**For AI Agents:**
- Automatically create PRs after completing features
- Check PR status and wait for CI checks to pass
- Add comments with analysis or suggestions
- Merge PRs after approval (when appropriate)

gh pr merge <number> --squash gh pr merge <number> --merge gh pr merge <number> --rebase


**针对AI Agent:**
- 完成功能后自动创建拉取请求
- 检查拉取请求状态，等待CI检查完成
- 添加包含分析或建议的评论
- 在获得批准后合并拉取请求（如适用）

Issue Management

问题管理

Create and Manage Issues:

bash

undefined

创建和管理问题:

bash

undefined

Create an issue

gh issue create --title "Bug: login fails" --body "Description of the bug"

List issues

gh issue list

View issue details

gh issue view <number>

Comment on issue

gh issue comment <number> --body "This is fixed in PR #123"

Close issue

gh issue close <number>

Reopen issue

gh issue reopen <number>


**For AI Agents:**
- Create issues for bugs discovered during code review
- Link issues to PRs automatically
- Update issue status based on PR status
- Create issues from TODO comments or technical debt

gh issue reopen <number>


**针对AI Agent:**
- 为代码审查中发现的bug创建问题
- 自动将问题与拉取请求关联
- 根据拉取请求状态更新问题状态
- 从TODO注释或技术债务中创建问题

Repository Operations

仓库操作

Repository Management:

bash

undefined

仓库管理:

bash

undefined

Clone a repository

gh repo clone owner/repo

View repository details

gh repo view

Create a new repository

gh repo create my-project --public --clone

Fork a repository

gh repo fork owner/repo

View repository settings

gh repo view --web


**For AI Agents:**
- Clone repositories for analysis or contribution
- Create new repositories with proper structure
- Fork repositories for experimentation

gh repo view --web


**针对AI Agent:**
- 克隆仓库用于分析或贡献
- 创建结构规范的新仓库
- 复刻仓库用于实验

Branch and Commit Operations

分支与提交操作

Branch Management:

bash

undefined

分支管理:

bash

undefined

List branches

gh repo view --json defaultBranchRef

Create branch from issue

gh issue develop <number> --branch feature/issue-123


**Browse GitHub Resources:**
```bash

gh issue develop <number> --branch feature/issue-123


**浏览GitHub资源:**
```bash

Open current PR in browser

gh pr view --web

Open current issue in browser

gh issue view --web

Open repository in browser

gh repo view --web

undefined

gh repo view --web

undefined

Search and Discovery

搜索与发现

Search Capabilities:

bash

undefined

搜索功能:

bash

undefined

Search code

gh search code "function authenticate"

Search repositories

gh search repos "react typescript"

Search issues

gh search issues "bug login"

Search pull requests

gh search prs "is:open author:@me"


**For AI Agents:**
- Search for similar implementations before creating new code
- Find existing issues or PRs related to current work
- Discover patterns and best practices from other repositories

gh search prs "is:open author:@me"


**针对AI Agent:**
- 在创建新代码前搜索类似实现
- 查找与当前工作相关的现有问题或拉取请求
- 从其他仓库中发现模式和最佳实践

API Access

API访问

Direct API Calls:

bash

undefined

直接API调用:

bash

undefined

Make authenticated API calls

gh api repos/:owner/:repo/pulls

Get specific data

gh api repos/:owner/:repo/pulls/123 --jq '.title, .body'

POST requests

gh api repos/:owner/:repo/issues -X POST -f title="New Issue" -f body="Description"


**For AI Agents:**
- Access GitHub API for advanced operations not covered by CLI commands
- Retrieve detailed data in JSON format for processing
- Perform bulk operations efficiently

gh api repos/:owner/:repo/issues -X POST -f title="New Issue" -f body="Description"


**针对AI Agent:**
- 访问GitHub API以执行CLI命令未覆盖的高级操作
- 以JSON格式检索详细数据用于处理
- 高效执行批量操作

Workflow Automation Examples

工作流自动化示例

Complete Feature Workflow:

bash

undefined

完整功能工作流:

bash

undefined

1. Create and checkout feature branch

git checkout -b feature/new-feature

2. Make changes and commit

git add . git commit -m "feat: implement new feature"

3. Push branch

git push -u origin feature/new-feature

4. Create PR

gh pr create --title "feat: implement new feature" --body "Description" --draft

5. Wait for CI checks

gh pr checks --watch

6. After approval, merge

gh pr merge --squash --delete-branch


**For AI Agents:**
- Automate the complete PR workflow from branch creation to merge
- Monitor CI checks and retry failed workflows
- Update PR descriptions with analysis or documentation
- Clean up branches after merge

gh pr merge --squash --delete-branch


**针对AI Agent:**
- 自动化从分支创建到合并的完整拉取请求工作流
- 监控CI检查并重试失败的工作流
- 使用分析或文档更新拉取请求描述
- 合并后清理分支

Best Practices for AI Agents

AI Agent最佳实践

Always authenticate first: Check
```
gh auth status
```
before operations
Use appropriate PR flags: Use
```
--draft
```
for work-in-progress,
```
--fill
```
to auto-populate from commits
Monitor CI checks: Use
```
gh pr checks --watch
```
to wait for checks to complete
Provide context: Always include meaningful titles and descriptions
Link related items: Reference issues in PR descriptions with
```
Closes #123
```
Handle errors gracefully: Check command exit codes and provide helpful error messages
Respect rate limits: Implement delays for bulk operations
Use JSON output: Use
```
--json
```
flag for programmatic processing

始终先进行身份验证: 执行操作前检查
```
gh auth status
```
使用合适的PR参数: 对进行中的工作使用
```
--draft
```
，使用
```
--fill
```
从提交中自动填充内容
监控CI检查: 使用
```
gh pr checks --watch
```
等待检查完成
提供上下文: 始终包含有意义的标题和描述
关联相关项: 在PR描述中使用
```
Closes #123
```
引用问题
优雅处理错误: 检查命令退出码并提供有用的错误信息
遵守速率限制: 对批量操作实现延迟
使用JSON输出: 使用
```
--json
```
标志进行程序化处理

git

Original

Translation

Git Skills & Best Practices

Git技能与最佳实践

Table of Contents

目录

Git Workflow

Git工作流

Conventional Commits

Conventional Commits

.gitignore

.gitignore

Environment variables

Environment variables

Dependencies

Dependencies

Build outputs

Build outputs

Testing

Testing

IDE

IDE

OS

OS

Logs

Logs

pnpm

pnpm

Misc

Misc

Git Hooks

Git钩子

Lefthook Integration

Lefthook集成

Pull Request Templates

拉取请求模板

Overview

Overview

Solution

Solution

Screenshots

Screenshots

Ticket

Ticket

Tested On

Tested On

Additional Notes

Additional Notes

GitHub CLI (gh) Integration

GitHub CLI (gh) 集成

Authentication

身份验证

Login to GitHub

Login to GitHub

Check authentication status

Check authentication status

Refresh authentication token

Refresh authentication token

Pull Request Management

拉取请求管理

Create a PR interactively

Create a PR interactively

Create a PR with title and body

Create a PR with title and body

Create a PR from current branch to main

Create a PR from current branch to main

Create a draft PR

Create a draft PR

List open PRs

List open PRs

View PR details

View PR details

View PR diff

View PR diff

Checkout PR locally

Checkout PR locally

Review PR status and checks

Review PR status and checks

Comment on PR