git-workflow（Git 工作流）

Git Workflow

Standardized Git workflow for commits, pull requests, and releases using conventional commits format and semantic versioning.

Prerequisites

Do NOT proactively verify these tools on skill load. If a command fails due to a missing tool, directly guide the user through installation and configuration step by step.

When to Use

• Creating commits: Follow conventional commits with concise, imperative messages
• Creating pull requests: Generate PR with clear description and test plan
• Creating releases: Update versions, CHANGELOG, tags, and GitHub releases

These workflows can be used independently or together as needed.

Platform Detection

Check git remote get-url origin to select workflow:

Quick Reference

Commit Format

type(scope): concise summary

- Optional bullet points (max 3-4)
- Keep short and focused

Types: feat, fix, refactor, docs, test, chore

Branch Naming

• feature/description
• fix/description
• docs/description
• refactor/description
• test/description

Release Checklist

1. Update version in project files
2. Update CHANGELOG.md
3. Commit: chore(release): bump version to x.y.z
4. Tag: git tag v{version} && git push upstream v{version}
5. Create GitHub release with gh release create

Default Behaviors

• Keep messages concise: Commit messages and PR titles must be short and to the point. Omit filler words. The diff shows "what" — the message explains "why".
• No AI signatures: Never include Co-Authored-By: Claude, Generated with Claude Code, or any AI markers in commits or PRs.
• Commit always pushes: After commit, always push immediately. Do not ask.

- Has upstream tracking → git push - No upstream tracking → git push -u origin <branch>

Detailed Guides

See examples-and-templates.md for commit examples (good/bad), PR body template, and CHANGELOG format.

Validation

Use scripts/validate_commit.py to validate commit messages:

python3 scripts/validate_commit.py "feat(auth): add OAuth2 support"
python3 scripts/validate_commit.py --file .git/COMMIT_EDITMSG

The validator checks:

• Conventional commits format
• Subject line length (< 72 chars)
• Imperative mood usage
• Absence of AI-generated markers
• Body format and bullet point count

Common Workflows

Commit (default: commit + push)

git add <files>
git commit -m "feat(component): add new feature" && git push

Pull Request

git checkout -b feature/new-feature
# ... make changes, commit (auto-pushes per default behavior) ...
gh pr create --title "feat(component): add new feature" --body "..."

Release

# Update version files + CHANGELOG.md
git add .
git commit -m "chore(release): bump version to 1.2.0" && git push
git tag v1.2.0 && git push upstream v1.2.0
gh release create v1.2.0 -R owner/repo --title "v1.2.0" --notes "..."

Common Issues