Git Commit Helper

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:

[optional scope]: 

[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)

(): 

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         # Multiple authors
Signed-off-by: Name          # Developer sign-off
Reviewed-by: Name            # 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:

(): 

Message Templates by Type

Feature Template

feat(): implement 

Add  that allows users to .

Implementation details:
- 
- 
- 

Refs: #

Bug Fix Template

fix(): resolve 

The fix:
- 
- 

Tested by:
- 

Closes: #

Refactoring Template

refactor(): 

Changes:
- 
- 

No functional changes. All existing tests pass.

Breaking Change Template

feat()!: 

Migration guide:
1. 
2. 
3. 

BREAKING CHANGE: 

Refs: #

Documentation Template

docs(): 

Changes:
- : 
- : 

Performance Template

perf(): optimize 

Optimization:
- 
- 

Benchmarks:
- Before: 
- After: 
- Improvement: 

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

## Alternative Messages

If multiple approaches are valid:
1. ``
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

Source & license

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

• Author: mehdiozdemir
• Source: mehdiozdemir/awesome-agent-skills
• License: MIT

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