ai/opencode
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5d9efea7ab414b6145456e8a3b9954f350aeafba
opencode/skill/git/SKILL.md
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

  1. Default Main Branch: Use main as the primary branch (not master)
  2. Conventional Commits: Follow Conventional Commits specification
  3. Semantic Versioning: Use major.minor.patch format (e.g., 0.1.0, 1.2.3)
  4. Repository Types: Support both polyrepo and monorepo workflows
  5. 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:

  1. Will this be packaged into the final product?
  2. Will users notice this change?
  3. 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

  1. Check AGENTS.md first: If version rules are defined, use them
  2. Auto-detect: Scan for version files based on project structure
  3. 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

  1. Check staging area:

    git diff --cached --name-only
    • If empty, add files first: git add .

  2. Collect information (in parallel):

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

  3. Determine repository type:

    • Check AGENTS.md for monorepo indicator
    • Analyze changed file paths for subproject scope

  4. 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

  5. Generate commit message:

    • Analyze changes
    • Follow Conventional Commits format
    • Include scope for monorepo single-project changes

  6. 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

  7. Commit changes:

    git commit -m "<message>"

  8. Create tag (if version updated):

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

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

  9. 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

  1. Always check staging area first: Don't commit empty staging area
  2. Verify version file is staged: After updating version, confirm with git diff --cached --name-only
  3. No --amend after push: Never amend commits that are already pushed
  4. Tag naming conflicts: Check existing tags before creating new ones
  5. Branch protection: Never force push to main/master without explicit user request
  6. 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
Reference in New Issue View Git Blame Copy Permalink