Smart Git Commit

Inspired by claude-code-plugins-plus

Purpose

Automatically generate meaningful commit messages by analyzing staged changes, following conventional commit format.

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Types

Type	Description
feat	New feature
fix	Bug fix
docs	Documentation only
style	Formatting, no code change
refactor	Code change, no new feature or fix
perf	Performance improvement
test	Adding/updating tests
chore	Maintenance tasks
ci	CI/CD changes
build	Build system changes

Scope

Optional, indicates the section of codebase:

• auth, api, ui, db, config, etc.

Subject

• Imperative mood ("add" not "added")
• No period at end
• Max 50 characters
• Lowercase

Body

• Explain WHAT and WHY, not HOW
• Wrap at 72 characters
• Separate from subject with blank line

Footer

• Breaking changes: BREAKING CHANGE: description
• Issue references: Closes #123, Fixes #456

Workflow

1. Analyze Changes

# View staged changes
git diff --staged

# View changed files
git diff --staged --name-only

# View stats
git diff --staged --stat

2. Determine Type

Based on changes:

• New files with features → feat
• Modified files fixing issues → fix
• Only .md files → docs
• Only test files → test
• package.json, configs → chore or build

3. Identify Scope

Look at file paths:

• src/auth/* → scope: auth
• src/api/* → scope: api
• tests/* → scope: test
• Multiple areas → omit scope or use broader term

4. Write Subject

Summarize the change:

feat(auth): add OAuth2 login support
fix(api): handle null response in user endpoint
docs: update README with installation steps
refactor(db): extract query builder to separate module

5. Write Body (if needed)

For complex changes:

feat(auth): add OAuth2 login support

Implement OAuth2 authentication flow with support for
Google and GitHub providers. This allows users to sign
in without creating a separate account.

- Add OAuth2 client configuration
- Implement callback handlers
- Store OAuth tokens securely
- Add provider selection UI

Examples

Simple Feature

feat(ui): add dark mode toggle

Bug Fix with Issue Reference

fix(api): prevent duplicate user creation

Check for existing email before inserting new user record.
Race condition could cause duplicate entries when requests
arrived simultaneously.

Fixes #234

Breaking Change

feat(api)!: change response format to JSON:API

BREAKING CHANGE: All API responses now follow JSON:API
specification. Clients must update their parsers.

Migration guide: docs/migration-v2.md

Multiple Files, Single Purpose

refactor: extract validation logic to shared module

Move duplicate validation code from controllers to
a shared validation module. Reduces code duplication
and ensures consistent validation across endpoints.

Anti-Patterns to Avoid

❌ "fix stuff"
❌ "update code"
❌ "WIP"
❌ "changes"
❌ "fixed bug"
❌ "misc updates"
❌ Commits with 50+ files and vague message

Best Practices

1. Atomic commits - One logical change per commit
2. Meaningful messages - Future you will thank present you
3. Reference issues - Link to tickets/issues when relevant
4. Review before commit - git diff --staged always
5. Don't commit secrets - Check for API keys, passwords

Quick Reference

# Stage specific files
git add <file>

# Stage all changes
git add -A

# Interactive staging
git add -p

# Commit with message
git commit -m "type(scope): subject"

# Commit with body
git commit -m "type(scope): subject" -m "body paragraph"

# Amend last commit
git commit --amend