ai/opencode
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1af6c39d258693c2b8399ef80f032717d0a24ea1
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

566 lines
13 KiB
Markdown
Raw Blame History

---
name: git
description: 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](https://www.conventionalcommits.org/) 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:**
```bash
feat: add user authentication with OAuth2
fix: resolve bluetooth connection timeout
docs: update API documentation
chore: update project dependencies
```
**Monorepo commits:**
```bash
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:**
```bash
<version>
Examples: 1.2.0, 0.3.1, 2.0.0
```
**Monorepo:**
```bash
<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:**
```bash
git tag -a "1.2.0" -m "feat: add user authentication"
```
**Multi-line example (recommended):**
```bash
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:**
```bash
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:**
```bash
git tag -a "<tag-name>" -m "<message>"
```
**Push single tag:**
```bash
git push origin <tag-name>
```
**Push all tags:**
```bash
git push --tags
# or
git push origin --tags
```
**List recent tags:**
```bash
git tag --list | sort -V | tail -5
```
**Delete local tag:**
```bash
git tag -d <tag-name>
```
**Delete remote tag:**
```bash
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):**
```bash
git status
```
**View unstaged changes:**
```bash
git diff
```
**View staged changes:**
```bash
git diff --cached
# or
git diff --staged
```
**List changed files only:**
```bash
git diff --name-only
git diff --cached --name-only
```
**View specific file changes:**
```bash
git diff <file-path>
git diff --cached <file-path>
```
### Staging and Committing
**Add files to staging area:**
```bash
git add <file>
git add .
git add -A
```
**Check what's staged:**
```bash
git diff --cached --name-only
```
**Commit with message:**
```bash
# 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:**
```bash
# 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:**
```bash
git push origin $(git branch --show-current)
# or
git push origin main
```
**Push with upstream tracking:**
```bash
git push -u origin <branch-name>
```
**Push all tags:**
```bash
git push --tags
# or
git push origin --tags
```
**Push specific tag:**
```bash
git push origin <tag-name>
```
**Push commit and tag together:**
```bash
git push origin main && git push origin <tag-name>
```
### Branch Operations
**View current branch:**
```bash
git branch --show-current
```
**List all branches:**
```bash
git branch -a
```
**Create new branch:**
```bash
git branch <branch-name>
git checkout -b <branch-name>
# or (modern)
git switch -c <branch-name>
```
**Switch branch:**
```bash
git checkout <branch-name>
# or (modern)
git switch <branch-name>
```
**Delete branch:**
```bash
git branch -d <branch-name>
git branch -D <branch-name> # force delete
```
### History and Logs
**View commit history:**
```bash
git log --oneline -10
git log --graph --oneline --all
```
**View recent tags:**
```bash
git tag --list | sort -V | tail -5
```
**View commit details:**
```bash
git show <commit-hash>
git show <tag-name>
```
**Search commit history:**
```bash
git log --grep="<pattern>"
git log --author="<name>"
```
## Workflow Best Practices
### Standard Commit Workflow
1. **Check staging area:**
```bash
git diff --cached --name-only
```
- If empty, add files first: `git add .`
2. **Collect information (in parallel):**
```bash
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:**
```bash
git commit -m "<message>"
```
8. **Create tag (if version updated):**
```bash
# Polyrepo
git tag -a "<version>" -m "<message>"
# Monorepo
git tag -a "<subproject>-<version>" -m "<message>"
```
9. **Push to remote:**
```bash
git push origin main
git push origin <tag-name> # if tag created
```
### Sync Configuration Workflow
**Pull latest config changes:**
```bash
cd ~/.config/opencode
git status # check for local changes
git pull origin main
git log --oneline -5 # view updates
```
**Push config changes:**
```bash
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:**
```bash
git status
git diff --cached --name-only
```
**Commit with tag:**
```bash
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:**
```bash
git push --tags
```
**View recent history:**
```bash
git log --oneline -10
git tag --list | sort -V | tail -5
```
**View changes:**
```bash
git diff # unstaged changes
git diff --cached # staged changes
git diff main..feature # compare branches
```
Reference in New Issue View Git Blame Copy Permalink