Enterprise Git Commit Workflow

This skill enforces Conventional Commits specification for enterprise projects, ensuring consistent, readable, and automatable commit messages.

Format

<type>[optional scope][!]: <description>

Required: Type and description Optional: Scope, breaking change indicator (!)

Commit Types

| Type | Purpose | |------|---------| | feat | New feature | | fix | Bug fix | | docs | Documentation only | | style | Code style (formatting, no logic change) | | refactor | Code restructuring (no behavior change) | | perf | Performance improvement | | test | Adding/updating tests | | build | Build system/dependencies | | ci | CI/CD configuration | | chore | Other maintenance tasks | | revert | Revert a commit |

For detailed type decision guidance, see commit-types.md.

Writing Style Rules

Imperative mood: Use "add" not "added" or "adds"
Lowercase first letter: "add feature" not "Add feature"
No trailing period: "add feature" not "add feature."
Subject max 72 chars: Total length including type/scope
Body wrap at 72: If adding a detailed body

Examples:

✅ feat(api): add user authentication
✅ fix(auth): resolve token expiration
❌ feat(api): Add user authentication.
❌ Updated the authentication flow

Workflow

1. Full Commit Workflow

When user requests creating a commit:

Analyze changes

git status
git diff --staged
git log -5 --oneline

Determine commit type - Use the decision tree in commit-types.md
Determine scope (optional) - Based on affected area (api, ui, auth, database, etc.)
Check for breaking changes - Does this break existing functionality?
Draft commit message following the format:
- Start with type and scope
- Add ! if breaking
- Add colon and space
- Write description in imperative mood
Stage files (if not already staged):
```
git add <files>
```
Validate commit message using the validation script (see below)

Create commit:

git commit -m "$(cat <<'EOF'
<type>[scope]: <description>

[optional body]

[optional footer]
EOF
)"

Run git status to verify success

2. Validate Commit Message

Use the validation script to check commit message format:

echo "feat(api): add user endpoint" | python3 scripts/validate_commit.py

The script checks:

Valid commit type
Proper format (type: description or type(scope): description)
Description not empty
Imperative mood (lowercase start)
No trailing period
Subject under 72 characters

Exit code: 0 for valid, 1 for invalid.

3. Generate Commit Message from Changes

To generate a commit message based on code changes:

Analyze the diff: git diff --staged
Identify the primary change type
Determine affected scope
Draft a concise description
Validate the message

Analysis prompts:

Multiple related changes → Group under single cohesive message
Mixed types → Split into multiple logical commits
Complex changes → Add body paragraph explaining context

Breaking Changes

For breaking changes, add ! after type/scope:

feat(api)!: remove deprecated endpoint

BREAKING CHANGE: The /users endpoint has been removed.
Use /v2/users instead.

Commit Message with Body

For complex changes, add a body:

feat(api): add user pagination

Implement cursor-based pagination for improved performance
with large datasets.

- Add before/after cursor parameters
- Limit max results to 100 per page
- Include pagination metadata in response

Closes #123

Common Patterns

Fix a bug

fix(auth): resolve session timeout issue

Add a feature

feat(api): add user search functionality

Update dependencies

chore(deps): upgrade react to v18

Refactor code

refactor(auth): extract token validation

Breaking change

feat(api)!: change authentication format

BREAKING CHANGE: API now requires Bearer token format.
Update all API clients accordingly.

Reference

Full specification: conventional-commits.md
Type decision guide: commit-types.md
Validation script: scripts/validate_commit.py