Git Workflow

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 focused

Types: feat, fix, refactor, docs, test, chore, style, ci, perf, build, revert

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
• Single-purpose commits: Each commit does one thing. If a change spans multiple types or scopes, split into separate commits before pushing.
• PR/MR description is prose, not template: subject + 2-3 declarative sentences explaining why + one 验证： / Verify: line. No markdown section headings inside the description, no emoji-bullets, no commit-list copy-paste. Full schema and forbidden patterns in [examples-and-templates.md](references/examples-and-templates.md#pr-description).

Detailed Guides

See [examples-and-templates.md](references/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 (

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

# 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 |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: niracler
• Source: niracler/skill
• License: MIT

Install and usage instructions live in the source repository linked above.