git-commit-helper

name	git-commit-helper
description	Creates professional, conventional commit messages following best practices. Use when committing code changes, reviewing staged files for commit message suggestions, generating changelogs, or ensuring commit history consistency across a team.

Git Commit Helper Skill

This skill generates clear, consistent, and informative commit messages following industry standards and best practices. Use this whenever you need to commit changes, review staged files, or ensure commit history quality.

Core Principles

1. Conventional Commits Standard

Follow the Conventional Commits specification:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

2. Atomic Commits

• Each commit should represent ONE logical change
• Changes should be self-contained and reviewable
• Avoid mixing unrelated changes
• Keep commits small and focused

3. Clear Communication

• Messages should explain WHAT changed and WHY
• Anyone reading the history should understand the change
• Use imperative mood ("Add feature" not "Added feature")
• Be specific, not vague

Commit Types

Standard Types

Type	Description	Example
feat	New feature for the user	feat(auth): add OAuth2 login support
fix	Bug fix	fix(api): resolve null pointer in user lookup
docs	Documentation only	docs(readme): update installation instructions
style	Formatting, no code change	style(lint): apply prettier formatting
refactor	Code change without fix/feature	refactor(utils): extract validation helpers
perf	Performance improvement	perf(db): add index for user queries
test	Adding/updating tests	test(auth): add unit tests for login flow
build	Build system or dependencies	build(deps): upgrade express to v5.0
ci	CI/CD configuration	ci(github): add automated testing workflow
chore	Other changes (no src/test)	chore(release): bump version to 2.0.0
revert	Revert previous commit	revert: feat(auth): add OAuth2 login support

Breaking Changes

Use ! after type/scope or BREAKING CHANGE: in footer:

feat(api)!: remove deprecated v1 endpoints

BREAKING CHANGE: The v1 API endpoints have been removed.
Migrate to v2 endpoints as documented in the migration guide.

Commit Message Structure

Subject Line (Required)

<type>(<scope>): <description>

Rules:

• Maximum 50 characters (hard limit: 72)
• Use imperative mood: "Add" not "Added" or "Adds"
• No period at the end
• Lowercase after the colon
• Scope is optional but recommended

Good Examples:

feat(auth): add password reset functionality
fix(cart): prevent duplicate item additions
refactor(api): extract response formatting logic
docs(contributing): add pull request guidelines
perf(images): implement lazy loading for gallery

Bad Examples:

❌ Fixed bug                          (too vague)
❌ feat: Added new feature.           (past tense, period)
❌ Update files                       (no type, vague)
❌ WIP                                (not descriptive)
❌ misc changes                       (meaningless)

Body (Optional but Recommended)

Provide additional context when the subject line isn't enough:

Include:

• Motivation for the change
• Contrast with previous behavior
• Side effects or caveats
• Reference to related issues

Format:

• Separate from subject with blank line
• Wrap at 72 characters
• Use bullet points for multiple items

Example:

fix(auth): prevent session fixation attacks

The previous implementation reused session IDs after login,
making the application vulnerable to session fixation attacks.

Changes:
- Regenerate session ID after successful authentication
- Clear old session data before creating new session
- Add security headers to session cookies

This follows OWASP recommendations for session management.

Footer (Optional)

Use for metadata and references:

Common Patterns:

Refs: #123                          # References issue
Closes: #456                        # Closes issue on merge
See-also: #789                      # Related issues
Co-authored-by: Name <email>        # Multiple authors
Signed-off-by: Name <email>         # Developer sign-off
Reviewed-by: Name <email>           # Code reviewer
BREAKING CHANGE: description        # Breaking change note

Scope Guidelines

What Makes a Good Scope?

• Component or module name: auth, cart, api, db
• Feature area: login, checkout, search
• File or directory: utils, config, models
• Layer: frontend, backend, infra

Scope Consistency

# Project-specific scopes (define in CONTRIBUTING.md)
auth      - Authentication and authorization
api       - REST/GraphQL endpoints
ui        - User interface components
db        - Database schema and queries
core      - Core business logic
config    - Configuration management
deps      - Dependencies
ci        - CI/CD pipelines
docs      - Documentation
test      - Test infrastructure

Commit Analysis Process

Step 1: Analyze Changes

When asked to create a commit message:

1. Review staged files: Understand what files changed
2. Identify change type: Is it a feature, fix, refactor, etc.?
3. Determine scope: Which component/module is affected?
4. Assess impact: Is this a breaking change?
5. Check relationships: Related issues or PRs?

Step 2: Assess Commit Quality

Evaluate if changes should be one or multiple commits:

# Single commit scenarios:
✅ One logical change across multiple files
✅ Feature with its tests
✅ Bug fix with regression test
✅ Refactor in one component

# Split into multiple commits:
⚠️ Unrelated bug fixes
⚠️ Feature + unrelated refactoring
⚠️ Multiple independent features
⚠️ Formatting changes + logic changes

Step 3: Generate Message

Create message following this template:

<type>(<scope>): <50-char description in imperative mood>

<Body explaining what and why, wrapped at 72 chars>

<Footer with references and metadata>

Message Templates by Type

Feature Template

feat(<scope>): implement <feature name>

Add <feature description> that allows users to <benefit>.

Implementation details:
- <Key implementation point 1>
- <Key implementation point 2>
- <Key implementation point 3>

Refs: #<issue-number>

Bug Fix Template

fix(<scope>): resolve <bug description>

<Root cause explanation>

The fix:
- <What was changed>
- <Why this solves the problem>

Tested by:
- <How it was verified>

Closes: #<issue-number>

Refactoring Template

refactor(<scope>): <what was refactored>

<Motivation for refactoring>

Changes:
- <Change 1>
- <Change 2>

No functional changes. All existing tests pass.

Breaking Change Template

feat(<scope>)!: <breaking change description>

<Explanation of the breaking change>

Migration guide:
1. <Step 1>
2. <Step 2>
3. <Step 3>

BREAKING CHANGE: <Detailed description of what breaks and why>

Refs: #<issue-number>

Documentation Template

docs(<scope>): <documentation change>

<What documentation was added/updated/removed>

Changes:
- <File/section 1>: <What changed>
- <File/section 2>: <What changed>

Performance Template

perf(<scope>): optimize <what was optimized>

<Performance problem description>

Optimization:
- <What was changed>
- <Expected improvement>

Benchmarks:
- Before: <metric>
- After: <metric>
- Improvement: <percentage>

Advanced Patterns

Multi-Component Changes

When a change affects multiple components:

feat(auth,api): add JWT token refresh mechanism

Implement automatic token refreshing to improve user experience.

Changes in auth module:
- Add token refresh endpoint
- Implement refresh token rotation

Changes in api module:
- Add middleware for automatic token refresh
- Update error handling for expired tokens

Refs: #234

Hotfix Pattern

fix(prod): emergency fix for payment processing

URGENT: Users were charged multiple times due to timeout 
handling issue in payment gateway integration.

Root cause: Missing idempotency key in retry logic
Fix: Add unique transaction ID for each payment attempt

Impact:
- Affected: ~50 transactions between 14:00-15:30 UTC
- Resolution: Automatic refunds processed

Refs: INC-456

Revert Pattern

revert: feat(search): add elasticsearch integration

This reverts commit abc123def456.

Reason: Elasticsearch cluster experiencing instability.
Will re-apply after infrastructure issues resolved.

Refs: INC-789

Merge Commit Pattern

Merge branch 'feature/user-dashboard' into main

Adds the new user dashboard feature including:
- Activity timeline
- Quick stats widgets
- Recent notifications panel

Refs: #123, #124, #125
PR: #200

Changelog Generation

From Commits to Changelog

Conventional commits enable automatic changelog generation:

# Changelog

## [2.1.0] - 2025-01-15

### Added
- feat(auth): add OAuth2 login support (#123)
- feat(dashboard): implement activity timeline (#124)

### Fixed
- fix(cart): prevent duplicate item additions (#125)
- fix(api): resolve null pointer in user lookup (#126)

### Changed
- refactor(utils): extract validation helpers (#127)
- perf(db): add index for user queries (#128)

### Breaking Changes
- feat(api)!: remove deprecated v1 endpoints (#129)

Semantic Versioning Mapping

Commit Type	Version Bump	Example
feat	Minor (x.Y.z)	1.0.0 → 1.1.0
fix	Patch (x.y.Z)	1.0.0 → 1.0.1
BREAKING CHANGE	Major (X.y.z)	1.0.0 → 2.0.0
Others	Patch (x.y.Z)	1.0.0 → 1.0.1

Best Practices

DO ✅

• Write in imperative mood ("Add feature" not "Added feature")
• Keep subject line under 50 characters
• Wrap body at 72 characters
• Separate subject from body with blank line
• Reference issues and PRs
• Explain WHY, not just WHAT
• Make atomic commits
• Use scopes consistently
• Include breaking change notes prominently

DON'T ❌

• Use vague messages like "fix bug" or "update code"
• Mix unrelated changes in one commit
• Write in past tense
• Exceed character limits
• Forget to reference issues
• Commit WIP or temporary code
• Use "misc", "various", or "stuff"
• Leave TODO comments without issue reference
• Commit commented-out code

Quality Checklist

Before finalizing a commit message:

• Type is correct and specific
• Scope identifies the affected component
• Subject is under 50 characters
• Subject uses imperative mood
• Subject is specific and meaningful
• Body explains WHY (if needed)
• Body is wrapped at 72 characters
• Breaking changes are clearly noted
• Related issues are referenced
• Commit represents ONE logical change

Common Scenarios

Scenario 1: Simple Bug Fix

Changes: Fixed typo in validation message

fix(validation): correct typo in email error message

Changed "Emal is required" to "Email is required".

Scenario 2: Feature with Tests

Changes: New logout functionality + tests

feat(auth): implement user logout functionality

Add secure logout that:
- Invalidates server-side session
- Clears authentication cookies
- Redirects to login page

Includes unit and integration tests.

Refs: #456

Scenario 3: Dependency Update

Changes: Updated React version

build(deps): upgrade react to v19.0

Update React and related dependencies:
- react: 18.2.0 → 19.0.0
- react-dom: 18.2.0 → 19.0.0
- @types/react: 18.2.0 → 19.0.0

No breaking changes in our codebase.
See React 19 migration guide for details.

Scenario 4: Configuration Change

Changes: Updated CI pipeline

ci(github): add code coverage reporting

Configure codecov integration:
- Add coverage upload step
- Set 80% coverage threshold
- Add coverage badge to README

Refs: #789

Scenario 5: Large Refactoring

Changes: Restructured authentication module

refactor(auth): restructure authentication module

Reorganize auth module for better maintainability:

Before:
  auth/
    index.js (1200 lines)

After:
  auth/
    index.js
    strategies/
      local.js
      oauth.js
      jwt.js
    middleware/
      authenticate.js
      authorize.js
    utils/
      token.js
      password.js

Benefits:
- Improved testability
- Better separation of concerns
- Easier to add new auth strategies

All existing tests pass. No functional changes.

Output Format

When generating commit messages, provide:

## Recommended Commit Message

```

Analysis

Type: - Scope: - Breaking: <Yes/No> -

Alternative Messages

If multiple approaches are valid:

1. <alternative 1>
2. <alternative 2>

Suggestions

```

Integration Tips

With Git Hooks (commitlint)

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'scope-enum': [2, 'always', ['auth', 'api', 'ui', 'db', 'core']],
    'subject-case': [2, 'always', 'lower-case'],
    'body-max-line-length': [2, 'always', 72]
  }
};

With Semantic Release

// .releaserc.json
{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/npm",
    "@semantic-release/github"
  ]
}

Notes

• Adapt message detail level to change complexity
• For trivial changes, a single subject line is sufficient
• For complex changes, detailed body is essential
• Always prioritize clarity over brevity when there's a tradeoff
• When in doubt, err on the side of more context
• Encourage team-wide adoption for maximum benefit