Git Workflow
Standardized Git workflow for commits, pull requests, and releases using conventional commits format and semantic versioning.
Prerequisites
| Tool | Type | Required | Install |
|---|---|---|---|
| git | cli | Yes | brew install git or git-scm.com |
| gh | cli | No | brew install gh then gh auth login (required for PR and Release) |
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:
| Remote URL contains | Commits/Tags/Releases | PR/MR |
|---|---|---|
github.com | This skill | This skill (gh pr create) |
codeup.aliyun.com | This skill | Switch to yunxiao skill |
gitlab.com | This skill | This skill (adapt for GitLab CLI) |
Quick Reference
Commit Format
type(scope): concise summary
- Optional bullet points (max 3-4)
- Keep short and focusedTypes: feat, fix, refactor, docs, test, chore
Branch Naming
feature/descriptionfix/descriptiondocs/descriptionrefactor/descriptiontest/description
Release Checklist
- Update version in project files
- Update CHANGELOG.md
- Commit:
chore(release): bump version to x.y.z - Tag:
git tag v{version} && git push upstream v{version} - 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_EDITMSGThe 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 pushPull 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
| Issue | Cause | Fix |
|---|---|---|
| Subject line > 72 chars | Description too long | Shorten summary, put details in body |
| Multiple types in one commit | Scope too large | Split into single-purpose commits |
| Merge commits appear | Used merge | Use git pull --rebase |
| Validator script errors | Format mismatch | Check type(scope): format |