Files

Voson 5a05d5ab53 chore: 重构 OpenCode 命令和技能文档体系

- 新增：统一的 git 命令文档（add/commit/push/pull 等）
- 新增：整合的 Gitea 技能文档（API、运行器、工作流等）
- 新增：工作流模板（Android、Go、Node.js 等）
- 移除：已弃用的旧命令脚本和发布脚本
- 改进：.gitignore 添加敏感文件保护规则
- 改进：AGENTS.md 完善了开发规范和示例

此次重组统一了命令和技能的文档结构，便于后续维护和扩展。

2026-01-13 00:27:21 +08:00

13 KiB

Raw Blame History

name, description

name	description
git	Git workflow best practices with commit conventions, tagging, and common operations for both polyrepo and monorepo

Git Workflow Best Practices

You are an expert in Git version control and repository management.

Core Principles

Default Main Branch: Use main as the primary branch (not master)
Conventional Commits: Follow Conventional Commits specification
Semantic Versioning: Use major.minor.patch format (e.g., 0.1.0, 1.2.3)
Repository Types: Support both polyrepo and monorepo workflows
Clean History: Maintain meaningful commit history and proper tagging

Repository Types

Polyrepo (Single Repository)

Each project has its own repository
Tag format: <version> (e.g., 1.2.0)
Version files at project root
Simpler workflow for independent projects

Monorepo (Multiple Subprojects)

Multiple projects in a single repository
Detect from AGENTS.md file or directory structure (e.g., packages/, apps/)
Tag format: <subproject>-<version> (e.g., ios-1.2.0, android-0.3.1)
Commit scope includes subproject name when changes affect single project
Each subproject maintains independent versioning

Monorepo Detection Rules:

Check if AGENTS.md explicitly indicates monorepo
Look for common monorepo directory structures:
- packages/, apps/, services/, modules/, projects/
If uncertain, default to polyrepo

Commit Message Convention

Format

<type>(<scope>): <subject>

<body>

<footer>

Commit Types

Type	Description	Version Impact	Examples
`feat`	New feature	minor +1	Add user authentication
`fix`	Bug fix	patch +1	Fix memory leak in cache
`perf`	Performance improvement	patch +1	Optimize database queries
`BREAKING CHANGE` or `!`	Breaking change	major +1	Remove deprecated API
`docs`	Documentation only	None	Update README
`style`	Code style/formatting	None	Fix indentation
`refactor`	Code refactoring	None	Reorganize file structure
`test`	Add/modify tests	None	Add unit tests for auth
`chore`	Maintenance tasks	None	Update dependencies
`ci`	CI/CD changes	None	Update workflow config
`build`	Build system changes	None	Update webpack config

Commit Message Language

Default (macOS/Linux): Use Chinese (中文)
Windows: Use English (due to Cursor Shell tool encoding issues)
Content: Focus on "why" rather than "what"
Length: Subject line ≤ 50 characters, body line ≤ 72 characters

Scope (for Monorepo)

When changes affect a single subproject, include scope:

Format: <type>(<scope>): <subject>
Example: feat(ios): add OGG Opus upload support
Example: fix(electron): resolve clipboard injection issue

When changes affect multiple subprojects or the entire repository, omit scope:

Example: chore: update shared dependencies

Examples

Polyrepo commits:

feat: add user authentication with OAuth2
fix: resolve bluetooth connection timeout
docs: update API documentation
chore: update project dependencies

Monorepo commits:

feat(ios): add OGG Opus upload support
fix(android): resolve memory leak in cache manager
refactor(electron): reorganize main process code
chore: update shared ESLint configuration

Version Management

Semantic Versioning

Format: major.minor.patch (e.g., 0.1.0, 1.2.3, 2.0.0)

Default starting version: 0.1.0
Major (X.0.0): Breaking changes, API incompatibility
Minor (0.X.0): New features, backward compatible
Patch (0.0.X): Bug fixes, backward compatible

Version Increment Rules

Change Type	Version Change	Example
Breaking change	major +1, reset minor/patch	`1.2.3` → `2.0.0`
New feature (`feat`)	minor +1, reset patch	`1.2.3` → `1.3.0`
Bug fix (`fix`)	patch +1	`1.2.3` → `1.2.4`
Performance (`perf`)	patch +1	`1.2.3` → `1.2.4`

When to Update Version

Update version (user-perceivable changes):

New features (feat)
Bug fixes that affect users (fix)
Performance improvements users can notice (perf)
Breaking changes (major version bump)

Don't update version (internal changes):

Documentation (docs)
Tests (test)
Refactoring without behavior change (refactor)
Code style (style)
Build configuration (build)
CI/CD changes (ci)
Maintenance tasks (chore)

Decision criteria:

Will this be packaged into the final product?
Will users notice this change?
Does it affect the product that users download/use?

If answer is "yes" → update version. Otherwise → skip version update.

Project Type Detection

Common Project Types

Project Type	Version File	Version Field
iOS	`*.xcodeproj/project.pbxproj`	`MARKETING_VERSION`
npm/Node.js	`package.json`	`version`
Android (Groovy)	`app/build.gradle`	`versionName`
Android (Kotlin DSL)	`app/build.gradle.kts`	`versionName`
Python (pyproject)	`pyproject.toml`	`[project] version` or `[tool.poetry] version`
Python (setup)	`setup.py`	`version`
Rust	`Cargo.toml`	`[package] version`
Go	Git tag only	-
Flutter	`pubspec.yaml`	`version`
.NET	`*.csproj`	`<Version>` or `<PackageVersion>`

Detection Strategy

Check AGENTS.md first: If version rules are defined, use them
Auto-detect: Scan for version files based on project structure
Fallback: If no version file found, only create Git tag (like Go projects)

Tag Management

Tag Format

Polyrepo:

<version>
Examples: 1.2.0, 0.3.1, 2.0.0

Monorepo:

<subproject>-<version>
Examples: ios-1.2.0, android-0.3.1, electron-2.0.0

Tag Annotation

Use same content as commit message for tag annotation
Tag annotations are used as Release notes by CI/CD
Multi-line commits should have multi-line annotations

Single-line example:

git tag -a "1.2.0" -m "feat: add user authentication"

Multi-line example (recommended):

git tag -a "1.2.1" \
  -m "fix: resolve bluetooth connection timeout" \
  -m "" \
  -m "- Increase connection timeout to 30s" \
  -m "- Add retry mechanism for failed connections" \
  -m "- Improve error messages"

Monorepo example:

git tag -a "android-1.2.1" \
  -m "fix(android): resolve bluetooth connection timeout" \
  -m "" \
  -m "- Increase connection timeout to 30s" \
  -m "- Add retry mechanism for failed connections"

Tag Operations

Create annotated tag:

git tag -a "<tag-name>" -m "<message>"

Push single tag:

git push origin <tag-name>

Push all tags:

git push --tags
# or
git push origin --tags

List recent tags:

git tag --list | sort -V | tail -5

Delete local tag:

git tag -d <tag-name>

Delete remote tag:

git push origin --delete <tag-name>
# or
git push origin :refs/tags/<tag-name>

Common Git Operations

Check File Changes

View changed files (working directory):

git status

View unstaged changes:

git diff

View staged changes:

git diff --cached
# or
git diff --staged

List changed files only:

git diff --name-only
git diff --cached --name-only

View specific file changes:

git diff <file-path>
git diff --cached <file-path>

Staging and Committing

Add files to staging area:

git add <file>
git add .
git add -A

Check what's staged:

git diff --cached --name-only

Commit with message:

# Single line
git commit -m "feat: add new feature"

# Multi-line (macOS/Linux)
git commit -m "$(cat <<'EOF'
feat: add new feature

- Detail 1
- Detail 2
EOF
)"

# Multi-line (Windows - use multiple -m flags)
git commit -m "feat: add new feature" -m "- Detail 1" -m "- Detail 2"

Commit and tag in workflow:

# 1. Check staging area
git diff --cached --name-only

# 2. Commit changes
git commit -m "feat: add user authentication"

# 3. Create tag
git tag -a "1.2.0" -m "feat: add user authentication"

# 4. Push both commit and tag
git push origin main
git push origin 1.2.0

Pushing Changes

Push current branch:

git push origin $(git branch --show-current)
# or
git push origin main

Push with upstream tracking:

git push -u origin <branch-name>

Push all tags:

git push --tags
# or
git push origin --tags

Push specific tag:

git push origin <tag-name>

Push commit and tag together:

git push origin main && git push origin <tag-name>

Branch Operations

View current branch:

git branch --show-current

List all branches:

git branch -a

Create new branch:

git branch <branch-name>
git checkout -b <branch-name>
# or (modern)
git switch -c <branch-name>

Switch branch:

git checkout <branch-name>
# or (modern)
git switch <branch-name>

Delete branch:

git branch -d <branch-name>
git branch -D <branch-name>  # force delete

History and Logs

View commit history:

git log --oneline -10
git log --graph --oneline --all

View recent tags:

git tag --list | sort -V | tail -5

View commit details:

git show <commit-hash>
git show <tag-name>

Search commit history:

git log --grep="<pattern>"
git log --author="<name>"

Workflow Best Practices

Standard Commit Workflow

Check staging area:
```
git diff --cached --name-only
```
- If empty, add files first: git add .

Collect information (in parallel):

git status
git diff --cached
git log --oneline -10
git tag --list | sort -V | tail -5

Determine repository type:
- Check AGENTS.md for monorepo indicator
- Analyze changed file paths for subproject scope
Auto-detect project type:
- Read AGENTS.md for version rules
- Scan for version files (package.json, build.gradle, etc.)
- Determine if version update is needed
Generate commit message:
- Analyze changes
- Follow Conventional Commits format
- Include scope for monorepo single-project changes
Update version number (if needed):
- Calculate new version based on change type
- Update version file
- Add version file to staging: git add <version-file>
- Verify: git diff --cached --name-only
Commit changes:
```
git commit -m "<message>"
```

Create tag (if version updated):

# Polyrepo
git tag -a "<version>" -m "<message>"

# Monorepo
git tag -a "<subproject>-<version>" -m "<message>"

Push to remote:

git push origin main
git push origin <tag-name>  # if tag created

Sync Configuration Workflow

Pull latest config changes:

cd ~/.config/opencode
git status  # check for local changes
git pull origin main
git log --oneline -5  # view updates

Push config changes:

cd ~/.config/opencode
git status  # check changes
git add command/ skill/ opencode.json
git commit -m "feat: add new git skill"
git push origin main

Platform-Specific Considerations

macOS/Linux

Commit language: Use Chinese (中文)
Multi-line commits: Use heredoc with cat <<'EOF'
Encoding: UTF-8 without BOM (default)

Windows

Commit language: Use English only (Cursor Shell encoding issue)
Multi-line commits: Use multiple -m flags
Prohibited methods:
- No Chinese commit messages
- No Out-File -Encoding utf8 (adds BOM)
- No PowerShell here-strings @"..."@
- No Write tool for temp files (encoding issues)

Error Prevention

Always check staging area first: Don't commit empty staging area
Verify version file is staged: After updating version, confirm with git diff --cached --name-only
No --amend after push: Never amend commits that are already pushed
Tag naming conflicts: Check existing tags before creating new ones
Branch protection: Never force push to main/master without explicit user request
Sensitive data: Never commit secrets, API keys, or credentials

Integration with CI/CD

Tag annotations: Used as Release notes
Version consistency: Git tag must match version file
Automated releases: Tags trigger CI/CD pipelines
Semantic versioning: CI/CD determines release type from version bump

Quick Reference

Check status:

git status
git diff --cached --name-only

Commit with tag:

git commit -m "feat: add feature"
git tag -a "1.2.0" -m "feat: add feature"
git push origin main && git push origin 1.2.0

Push all tags:

git push --tags

View recent history:

git log --oneline -10
git tag --list | sort -V | tail -5

View changes:

git diff                 # unstaged changes
git diff --cached        # staged changes
git diff main..feature   # compare branches

13 KiB Raw Blame History

Git Workflow Best Practices

Core Principles

Repository Types

Polyrepo (Single Repository)

Monorepo (Multiple Subprojects)

Commit Message Convention

Format

Commit Types

Commit Message Language

Scope (for Monorepo)

Examples

Version Management

Semantic Versioning

Version Increment Rules

When to Update Version

Project Type Detection

Common Project Types

Detection Strategy

Tag Management

Tag Format

Tag Annotation

Tag Operations

Common Git Operations

Check File Changes

Staging and Committing

Pushing Changes

Branch Operations

History and Logs

Workflow Best Practices

Standard Commit Workflow

Sync Configuration Workflow

Platform-Specific Considerations

macOS/Linux

Windows

Error Prevention

Integration with CI/CD

Quick Reference

13 KiB

Raw Blame History