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

text

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

•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:

bash

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)

bash

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

Pull Request

bash

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

bash

# 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